> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # How Lerian SPI works > How Lerian SPI works: Pix onboarding, send and receive flows (pacs.008 and pacs.002), returns, DICT keys and claims, BR Code charges, Pix Automático, and MED. 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.