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.

​
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 spi.payment.settled to close a charge after its Pix settles and spi.mandate.resolved to move a Pix Automático mandate out of CRIADA.
  • 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. You must request a return within 90 days of that payment’s settlement. A return may not push the sum of the Pix’s returns past the Pix’s own value. The counterparty issues a return of a Pix your client sent. This return 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 receives an in-progress answer. A colliding return identifier receives a conflict answer, never a receipt.
  • Inbound rail messages are signature-validated. The rail does not apply a message that fails validation.