PIX
PIX: a reference architecture for instant settlement
PIX changed the availability bar for the Brazilian financial market: there's no maintenance window, no "temporarily down for scheduled maintenance." Any integration has to run 24 hours a day, 7 days a week, 365 days a year — New Year's Eve included.
The three contracts that matter
A well-architected PIX integration treats three contracts as first-class citizens:
- Initiation — the payer submits the order, which needs to be validated, signed and routed to the SPI in milliseconds.
- Receiving — the payee needs to be notified and have the amount reflected in their balance before they even open the app again.
- DICT — the key directory needs to answer lookups consistently, even under traffic spikes on high-demand dates.
Idempotency is not optional
Every message exchanged with the SPI can be retransmitted. A core banking architecture that doesn't handle idempotency end to end — from the API endpoint all the way to the ledger write — is exposed to duplicate entries. Best practice is:
- A unique idempotency key per
endToEndId. - Deduplication at the edge (API Gateway) and again at the ledger write.
- Safe reprocessing driven by a state machine, never by "blind" retries.
Reconciliation as a continuous process
Reconciliation shouldn't be an end-of-day job. In an event-driven architecture, every SPI confirmation triggers an event that simultaneously updates the ledger, the customer's statement, and the partner webhook bus — cutting divergence down to seconds, not hours.
The result is a platform where availability, consistency and speed stop being conflicting goals.