> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrating with Lerian SPI

> The inbound BACEN callbacks, event-driven backbone, Midaz ledger touchpoint, and API conventions for building on Lerian SPI.

Lerian SPI is event-driven. Operations and settlement changes flow as domain events on the platform's streaming backbone, so downstream systems on the platform react to state changes without polling. The native rail has **no client-facing webhook consumers** — its coordination is internal to the platform.

## Inbound from BACEN

***

BACEN posts signed ISO 20022 XML callbacks over the RSFN — a credit-transfer message (`pacs.008`) for an inbound Pix, a status reply (`pacs.002`) for a payment you sent, and a return message (`pacs.004`) for a devolução. The rail validates each callback's signature before applying it, and returns a signed response where the protocol requires one. A payment you send stays open until its `pacs.002` arrives and moves it to `settled` or `rejected`, with BACEN's fields projected verbatim.

## Event flow

***

Each context on the rail publishes and consumes the events it owns:

* The **BR Code** context publishes charge events and the recurring-family (Pix Automático) events, and consumes settlement events to close out a charge once its Pix settles.
* The **Core** context consumes participant-confirmation events and settlement completion and termination events, keeping participant and operation state in step with BACEN.

## Midaz touchpoint

***

Settlement is booked in the **Midaz** ledger. Lerian SPI holds **no** accounting position of its own — it reconciles its state by consuming Midaz settlement events, so the rail's view of a payment and the ledger's postings stay aligned. The rail carries the message and its settlement state; Midaz records the money.

## API conventions

***

* **Auth** follows the platform's standard bearer-token scheme.
* **Payments are addressed by end-to-end ID.** A payment, its history, and its operation timeline are read back by E2EID.
* **Returns are sub-resources.** A devolução is created and read under the parent payment it reverses, so a return is always tied to a settled operation.
* **Inbound callbacks are signature-validated.** A callback that fails signature validation is not applied.