Skip to main content
Lerian SPI exposes the Pix message surface as a set of typed operations. The rail sends the messages of these operations as your direct participant, the ISPB in BACEN_SPI_PARTICIPANT_ISPB:
  • the connectivity test;
  • the Conta PI report request and the responsáveis registration;
  • the Pix Automático mandate request, cancellation, and resolution (pain.009, pain.011, pain.012);
  • the Pix Automático schedule instruction, resolution, and cancellation (pain.013, pain.014, camt.055);
  • the MED 2.0 settlement report.
Their request bodies take no participantIspb, and a body that carries it gets 422.

​
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. Offboarding a direct participant makes it OFFBOARDED at once. Offboarding an indirect participant moves it to OFFBOARD_PENDING, and the rail sends BACEN a reda.031. BACEN’s reda.016 answer makes the participant OFFBOARDED, or ACTIVE again if BACEN refuses. While the reda.031 waits for that answer, a new offboard request gets 409 with code SPI-3010. When the rail knows that the reda.031 did not reach BACEN, you can send the offboard request again.

​
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. When the rail cannot open a connection to BACEN, the regulatory archive refuses the write, or the rail cannot build the message, and no earlier attempt may have reached BACEN, the payment ends FAILED, and the request gets 503 with code SPI-1001. A Pix payment that ended FAILED because the connection to BACEN failed or the transport security check failed (503 with SPI-1001 or SPI-1004) can be sent again. Under the same X-Idempotency key, send the first request again exactly as it was. Under a new key, send the same request with the endToEndId of the failed payment. The rail sends it as a new attempt on the same payment, and publishes spi_payment.initiated again. A return in the same cases ends NAO_REALIZADO, with the same answer, and is never sent again this way. A return that BACEN refuses with 401 or 403 also ends NAO_REALIZADO, and the rail releases its return ceiling, unless an earlier attempt may have reached BACEN. An operation that needs attention appears in the stuck-operations list, with the actions it accepts. You submit an action with a reason. Manual resolution closes a stuck operation. It needs an APPROVED approval for that operation. An approval request takes only the subject type MANUAL_RESOLUTION, and its subjectId is the operation to resolve. For a sent Pix or a return that BACEN did not answer, the resolution declares the outcome in outcome: SETTLED or REJECTED. The approval names the same outcome in requestedAction: MANUAL_RESOLVE_SETTLED or MANUAL_RESOLVE_REJECTED. A SETTLED declaration also carries BACEN’s settlement instant from the evidence, in settledAt. The rail closes the Pix as a pacs.002 does and publishes spi_payment.settled or spi_payment.rejected. A later BACEN answer does not change the Pix. A SETTLED return closes DEVOLVIDO, and the rail publishes spi_payment.returned or spi_payment.partial_returned. A REJECTED return closes NAO_REALIZADO, and the rail publishes spi_payment.return_rejected or spi_payment.partial_return_failed. A full return that is REJECTED also returns its Pix to COMPLETED. A later BACEN answer does not change the return. When BACEN does not answer a sent Pix or a return by its deadline, its row offers RECONCILE_WITH_BACEN. With that action, the rail asks BACEN for the payment’s entry (camt.060). When BACEN’s camt.054 answer reports the payment as settled or rejected, the rail completes or rejects it, as a pacs.002 does. Any other answer leaves the payment open. A return’s stuck row offers only that action. The manual resolution of a return runs on its PAYMENT_RETURN operation.

​
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 a FRAD refusal as FRAD only when your client marks it as the decision of its antifraud system. Without the mark, the rail answers DS04. 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. The spi_payment.received event carries the end of the regulatory window in decisionDeadline. A Pix Agendado (PAGAGD) has 45 minutes and a fraud-suspect Pix (PAGFRD) has 40 seconds, both from the SPI’s receipt. Any other Pix has 40 seconds from the moment the payer’s institution accepted the order. The rail keeps the last 6 seconds of each window for the work after the 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. An inbound return does not settle on arrival. The rail holds it and announces it in a studio.lerian.br-spi.spi_payment.return_received event that carries its returnId. Your client decides the return by that returnId: it authorizes the return, or it refuses it with a reason. An authorized return settles only when the SPI confirms it. The rail refuses a return that no decision concludes within its window, and a later decision gets 409. Two return surfaces exist, the devolução request and the payment return. The rail records which one created a return rather than inferring it later. A devolução request is always partial, whatever its value, and uses the devolucaoId you choose as its key. A payment return for less than the Pix value is also partial and needs a devolucaoId. A payment return for the whole value is full: it reverses the whole Pix and moves the parent payment out of COMPLETED. A partial return leaves the parent payment settled, and several partial returns can coexist for one Pix. When the settled partial returns reach the Pix value, the parent payment moves to RETURNED. 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. A return that ends NAO_REALIZADO does not count. The rail reads only that payment’s amount and its own returns. It computes no position across payments.
A transport acceptance is not a conclusion. A devolução request takes the nature ORIGINAL (the default when you send none) or RETIRADA, the Pix Saque and troco leg. A payment 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 register, update, and delete Pix keys against the DICT directory. You also list, search, and look up keys, and batch-check whether a set of keys exists. You read one key from the rail’s own registry without a query to BACEN. The rail reads DICT key statistics and BACEN antifraud statistics, both per key and per person. For directory synchronization, the rail exposes BACEN’s VSync operations. It verifies a CID set, resolves a CID, and lists CID set events. It also requests and streams a CID set file.

​
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. You can abandon an open claim that BACEN never registered. The claim ends CANCELLED, and the rail sends nothing to BACEN.

​
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). On the payer side, you resolve a scanned dynamic QR into its charge. The rail returns the charge only after the receiver’s site certificate and the payload signature pass its checks.

​
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.
The pain.014, camt.029, and camt.055 requests take only the decision. The rail reads the participants, the identifiers, the EndToEndId, the creditor agent, and the creditor tax ID from the pain.013 or camt.055 that it recorded. Any other field gets 422.
  • The pain.014 takes originalScheduleId, accepted, rejectReason, and an optional endToEndId.
  • The camt.029 takes cancellationCorrelationId, accepted, and rejectReason.
  • The camt.055 takes cancellationId, scheduleId, originatorTaxId, reasonCode, and an optional endToEndId. The rail accepts the reasons CCLD and FAIL only when your institution is the payer’s participant on the schedule.
Only the payer’s participant answers a pain.013, and only the participant that received a pain.009 or pain.011 answers it with a pain.012. A pain.014 for a schedule that this installation sent, and a pain.012 for a request that this installation sent, get 422 with code SPI-0003. A received pain.013 retry (purpose NTAG or RIFL) opens its own schedule beside the charge’s and publishes its own spi_schedule.requested. The optional endToEndId on the pain.014 and the camt.055 selects that attempt, and an unknown value gets 404. When the receiver’s participant refuses a CFDB that the rail sent, the mandate moves to AUTHORIZATION_REFUSED, and the rail publishes spi_mandate.resolved. The rail does not process a resent camt.055 again. When its camt.029 already reached BACEN, it sends that camt.029 again. When the rail sends a camt.055 and no camt.029 answers it, the rail sends it again 1, 3, and 6 hours after the first send: at most three times, and never at or after 11 hours. If no camt.029 answers within 12 hours of the first send, the cancellation takes effect: the rail cancels the schedule and publishes spi_schedule.resolved. If BACEN may not have received the camt.055, or if the charge can already have settled, the rail moves the operation to REQUIRES_OPERATOR_ACTION instead. When the rail sends a pain.011 and no pain.012 answers it within 12 hours, the mandate becomes CANCELLED, and the rail publishes spi_mandate.resolved. A pain.011 with the reason PCFD returns the mandate to ACTIVE, and the rail publishes no event. A pain.011 without a recorded BACEN acceptance goes to the operator. A pain.012 after that does not move the mandate. The rail can reject a received cancellation request (camt.055) with a camt.029. If BACEN refuses that camt.029 and accepts no resend within 12 hours after the camt.055 arrived, the rail cancels the schedule. If the charge can already have settled, the rail keeps the schedule and moves its operation to REQUIRES_OPERATOR_ACTION. List the replies BACEN refused lists the pain.014 and camt.029 replies that an admi.002 or an operator release left FAILED, soonest deadline first. Each row shows the time left to resend. The route that sent the reply resends the same verdict before the deadline: 2 hours after the pain.013 arrived, or 12 hours after the camt.055 did. Send the resend with a new X-Idempotency key: under the first key, the rail replays its first answer and sends nothing to BACEN.

​
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). The report always covers the Conta PI of your direct participant. 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. You also register the Conta PI responsáveis of your direct participant (reda.022), and you read back their last-known record.

​
Regulatory archive

Lerian SPI archives each ICOM envelope that it sends to or receives from BACEN, and each DICT request and answer, with their headers. It also archives the certificates that sign or verify them. Each item carries its retention period from the Manual de Segurança do SFN, chapter 7. If the rail cannot archive an outbound message, it does not send it. GET /api/v1/spi/regulatory-archive/{itemId} returns one archived item byte for byte, so you can verify its signature again. The route accepts only a user, not an application, with the Access Manager resource br-spi-regulatory-archive and the action read. The rail records who read which item and when before it returns the content. A read that the rail cannot record returns nothing. You configure the archive storage with the REGULATORY_ARCHIVE_* environment variables. Only a development environment can start without it.