Skip to main content
Lerian SPI exposes the Pix message surface as a set of typed operations. Most flows persist their work before dispatch; the return dispatcher only attempts to record an outbound pacs.004 before submitting it, and a recording failure does not necessarily block dispatch. Operations return an accepted-but-not-settled state and reconcile against BACEN’s asynchronous reply.

​
Onboarding and readiness

You register a participant by its ISPB. An indirect participant enters PENDING; the rail sends its registration request, and only BACEN’s confirmation can make it active. The activation action only reactivates an already-suspended participant. The rail runs readiness in a required order. A passing connectivity test is the prerequisite for a submit.
  1. Upload a Pix certificate — the public .cer only. The rail rejects an uploaded private key.
  2. Confirm the rail reports ready.
  3. Pass a connectivity test.
  4. You can now submit payments.
The same Core surface also suspends and offboards a participant over its lifecycle.

​
Send a Pix

You create a payment order. The platform builds the ISO 20022 credit-transfer message (pacs.008), persists the operation, and dispatches it. BACEN returns an asynchronous status callback (pacs.002). The rail validates and applies it, then moves the payment to completed or rejected. You read a payment back by its end-to-end ID, with its history and a per-operation timeline.

​
Receive a Pix

The ICOM consumer receives signed BACEN messages and passes them to the rail’s authenticated internal ingress. For an inbound pacs.008, the rail validates the message and records the Pix as pending. The client then supplies the funding decision for that already-received Pix. An outbound payment cannot be funded as incoming money. Participants list the Pix they receive.

​
Return (devolução)

You initiate a return (pacs.004) only for a settled Pix that the rail received from BACEN, then read the return’s status. The return debits the original recipient and credits the original payer. You cannot initiate a return for a Pix your client sent; a return of that Pix is issued by the counterparty and reaches the rail as an inbound message. A return is the MED money-movement path — the way funds flow back to a payer for a completed dispute or error. Two return surfaces exist, and the rail records which one created a return rather than inferring it later. A full return reverses the whole Pix and moves the parent payment out of completed. A partial return is keyed by the devolucaoId you choose and never moves the parent payment. Several partial returns can coexist for one Pix. Three gates apply to every return, on both surfaces:
  • The parent must be an inbound Pix that settled. Only a received payment that reached completed — or that already carries a return — can be returned.
  • BACEN’s return window. A return must be requested within 90 days of the original Pix settlement, and the rail measures the window from the settlement instant, never from creation or from the last update. A Pix with no recorded settlement instant is not blocked: the rail logs the gap and forwards the request.
  • The sum ceiling. The values of all returns of one Pix may not exceed that Pix’s own value. The rail reads only that payment’s amount and its own returns; it computes no position across payments.
A return is born EM_PROCESSAMENTO and reaches DEVOLVIDO or NAO_REALIZADO only on BACEN’s answer — a transport acceptance is not a conclusion. A return that fails releases the ceiling it was holding, and a failed full return returns the parent payment to completed without rearming its 90-day window. You request a return as ORIGINAL (the default when you send no nature) or RETIRADA, the Pix Saque and troco leg. The two MED natures — operational failure and founded fraud suspicion — are response-side only: they follow from the reason the rail puts on the pacs.004, and you never ask for them.

​
DICT key lifecycle

You manage Pix keys directly against the DICT directory: register, list, search, look up, update, and delete a key. You also batch-check whether a set of keys exists. The rail reads DICT key statistics and BACEN antifraud statistics, both per key and per person.

​
DICT claims (reivindicação)

A claim moves a Pix key between participants for portability or ownership. You initiate a claim against a participant, then move it through its lifecycle. The lifecycle covers acknowledge, confirm or reject, and complete or cancel, across the donor and claimer sides. When both SCHEDULER_ENABLED=true and SCHEDULER_CLAIM_DEADLINE_ENABLED=true, the rail registers periodic claim-deadline processing. It attempts to advance claims against their BACEN windows, but a claim can still require attention.

​
BR Code and charges

A dynamic QR resolves to a persisted charge, so you create the charge first, then generate the payload that resolves to it. A static QR is generated from static payment input; it neither requires nor points to a charge.
  • Create a charge: Cob (immediate), CobV (due-date, with interest and fine), or a batch of due-date charges.
  • Generate the dynamic EMV QR payload, which links to the charge by its txid or locator and resolves as a signed JWS.
You also generate a static QR, decode a payload, validate it, and register a receiver profile (recebedor).

​
Pix Automático (recurring)

Pix Automático authorizes recurring and scheduled payments through the ISO 20022 recurring family:
  • Create a recurring authorization (recorrência) or a request for one.
  • Request confirmation of the mandate (pain.009), cancel it (pain.011), or accept / reject it (pain.012).
  • Schedule an instruction (pain.013) and accept / reject it (pain.014).
  • Request cancellation of a scheduled instruction (camt.055) and resolve a received cancellation (camt.029).
  • Request a settlement retry (retentativa) when a scheduled charge misses.

​
MED disputes

The MED (Mecanismo Especial de Devolução) surface handles fraud and error cases end to end:
  • Open a MED case, analyze it, then resolve, close, or cancel it with attached evidence.
  • File DICT infraction reports, refund requests, fraud markers, and funds-recovery requests, each tracked through its lifecycle graph.
  • Report internally-settled Pix through the MED 2.0 settlement report.

​
Conta PI reporting

You request an account report (camt.060), then read the balance (camt.053), statement (camt.052), or entry detail (camt.054) that BACEN returns. Synchronous count-only volumetria, rejected-payments, balance, and extract reports round out the reporting surface, each windowed to its reference period.