Skip to main content
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.