> ## 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. 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 receive funding 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. 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. 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: * **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.