> ## 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

> The onboarding sequence, send and receive flows, returns, DICT keys and claims, BR Code charges, Pix Automático, and MED disputes that make up the Pix message surface.

Lerian SPI exposes the Pix message surface as a set of typed operations. Each flow persists its work before dispatch, returns an accepted-but-not-settled state, and reconciles against BACEN's asynchronous reply.

## Onboarding and readiness

***

A participant is registered by its ISPB and activated before it can transact. Readiness then runs in a mandatory order, and a submit attempted before it passes is refused.

1. **Upload** a Pix certificate — the public `.cer` only. An uploaded private key is rejected.
2. Confirm the rail reports **ready**.
3. Pass a **connectivity test**.
4. Submits are now permitted.

Participants are suspended and offboarded over their lifecycle through the same Core surface.

## 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`) that the rail validates and applies, moving the payment to `settled` or `rejected`. A payment is read back by its end-to-end ID, along with its history and a per-operation timeline.

## Receive a Pix

***

BACEN posts a signed `pacs.008` XML callback for an inbound Pix. The rail validates the signature, applies the payment, and returns a signed `pacs.002` response. Participants list the Pix they have received.

## Return (devolução)

***

On a settled payment, you initiate a return (`pacs.004`) as a sub-resource of the parent operation, then read the return's status. A return is the MED money-movement path — the way funds flow back to a payer for a completed dispute or error.

## DICT key lifecycle

***

Pix keys are managed directly against the DICT directory: register, list, search, look up, update, and delete a key, and batch-check whether a set of keys exists. The rail also 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 — acknowledge, confirm or reject, complete or cancel — across the donor and claimer sides. Claim deadlines are processed automatically so a claim cannot stall past its BACEN window.

## BR Code and charges

***

A QR always points at a charge, so you create the charge first, then generate the payload that resolves to it.

* 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.

Static QR generation, decode, validation, and receiver-profile (recebedor) registration are also part of the surface.

## 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, carrying a composite QR.
* **Confirm** 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, statement, or entries result BACEN returns (`camt.052` / `camt.053` / `camt.054`). Synchronous count-only volumetria, rejected-payments, balance, and extract reports round out the reporting surface, each windowed to its reference period.