Skip to main content
Lerian SPI exposes the Pix message surface as a set of typed operations. Operations return an accepted-but-not-settled state and reconcile against BACEN’s asynchronous reply.

​
Onboarding and readiness

You register an indirect participant by its ISPB. It enters PENDING, and the rail sends its registration request. Only BACEN’s confirmation makes it ACTIVE. A BACEN refusal makes it REGISTRATION_REJECTED. The activation action only reactivates a SUSPENDED participant. The recommended preparation order before you submit payments is:
  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. 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 reply (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. Your client then decides that Pix in one of three ways. It sends funding evidence (available balance, available limit, risk score) for the rail to assess, it states that it already authorized the credit, or it sends a refusal reason. The rail answers an accepted Pix to the SPI, and the Pix reaches COMPLETED only when the SPI confirms the credit, or REJECTED if the SPI refuses it. The rail refuses a Pix that no decision concludes within its regulatory window, and a later decision gets 409. An outbound payment cannot receive funding as incoming money. You list the Pix you receive, and the Pix still waiting for a decision.

​
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. The counterparty issues a return of that Pix, and it 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 uses the devolucaoId you choose as its key 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. 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 held. A failed full return returns the parent payment to COMPLETED without rearming its 90-day window. A partial return takes the nature ORIGINAL (the default when you send none) or RETIRADA, the Pix Saque and troco leg. A full return takes a reason: MD06, SL02, BE08, or FR01. The two MED natures (operational failure and founded fraud suspicion) follow from BE08 and FR01. You never request them as a nature.

​
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. The claim-deadline job runs by default and advances claims against their BACEN windows. 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

You handle MED (Mecanismo Especial de Devolução) fraud and error cases in DICT, and report internal settlements on SPI:
  • File DICT refund requests, fraud markers, and funds-recovery requests. A funds recovery is tracked through its lifecycle graph.
  • Read, acknowledge, cancel, close, and refresh DICT infraction reports.
  • Report internally-settled Pix through the MED 2.0 settlement report.

​
Conta PI reporting

You request an account report (camt.060) for the balance (camt.053), the statement (camt.052), or the entry detail (camt.054). You read the balance and the statement back through the API. Synchronous reports round out the reporting surface: a count-only volumetria, a rejected-payments count with a paginated list, and balance and extract listings. Each report window spans at most 92 days.