Skip to main content
Lerian SPI is event-driven. Operations and settlement changes flow as domain events on the platform’s streaming backbone. Downstream systems react to these changes without polling. The native rail has no client-facing webhook consumers. Its coordination is internal to the platform.

​
Inbound from BACEN

The ICOM consumer receives signed ISO 20022 messages from BACEN over the RSFN and passes them to the rail’s authenticated internal ingress. A credit-transfer message (pacs.008) carries an inbound Pix. A status reply (pacs.002) reports a payment you sent. A return message (pacs.004) carries a devolução. The rail validates each inbound message before it applies it. An outbound payment stays open until its pacs.002 arrives; that reply applies COMPLETED or REJECTED. An inbound pacs.008 is recorded pending and is completed or refused by the authenticated client’s funding decision. The rail records BACEN’s fields 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. It consumes settlement events to close a charge after its Pix settles.
  • The Core context consumes participant-confirmation events and settlement completion and termination events. It keeps participant and operation state in step with BACEN.

​
Ledger integration

Lerian SPI holds no accounting position of its own. The rail emits settlement events on the streaming backbone, and your ledger consumer records the corresponding position. The rail relays each settled value verbatim. Each settlement event carries a stable ce-id that identifies the settlement; delivery is at-least-once, so your ledger consumer must deduplicate redeliveries by ce-id.

​
API conventions

  • Auth follows the platform’s standard bearer-token scheme.
  • Payments carry an end-to-end ID. You read a payment and its history back by E2EID.
  • Returns are sub-resources. You create and read a devolução under the inbound parent payment it reverses. A return must be requested within 90 days of that payment’s settlement and may not push the sum of the Pix’s returns past the Pix’s own value. A return of a Pix your client sent is issued by the counterparty and arrives inbound.
  • A return concludes on BACEN’s answer. A pacs.004 the rail dispatched stays in progress until BACEN answers it. A duplicate request for a return already in progress is answered as in progress, and a colliding return identifier is answered as a conflict — never as a receipt.
  • Inbound rail messages are signature-validated. The rail does not apply a message that fails validation.