Skip to main content
Direct Pix via JD makes your institution a direct participant in Pix: present at BACEN’s settlement system (SPI) and key directory (DICT) in its own right, connected through JD’s certified infrastructure (JDPI). Your institution owns its Pix participation; JD provides the regulated connectivity that reaches BACEN’s network. If the rail itself is new to you — modalities, SPI, DICT, participation models — start with What is Pix?. Everything the rail does is one API, and its OpenAPI specification is the source this documentation derives from: every operation carries the rules an integrator cannot guess from the schema alone.
Everything on these pages that provisions or configures the rail describes a single-tenant deployment, where your team operates the service. On Lerian’s managed multi-tenant offering (SaaS), everything client-specific — JD credentials, the public QR domain, the Midaz ledger binding, the CRM connection, and every service the rail talks to — is provisioned and resolved automatically, per tenant, by the platform. There is nothing for you to configure beyond your own integration.

​
One tenant, one direct participant

A tenant is a direct participant. Every call is authenticated with the direct participant’s own machine-to-machine credentials, and the tenant comes from the validated bearer — never from a payload or a path. The institutions you host as indirect participants live inside your tenant and never hold a credential of their own. An indirect’s id on a request is routing data: it decides which settlement position the money moves on, and the guarantee that the request really belongs to that institution is yours to make before you send it. The one anonymous exception is the public QR payload and JWKS routes, whose caller is the payer’s PSP — a party that was never registered with you.

​
The domain map

Each domain below is a section of the API reference. One sentence here; the reference carries the full contract — when each operation is called, by which side, and what it refuses. Each link lands on a representative operation of its section.
  • Key entries — register, change, and remove the PIX keys bound to your accounts in the DICT, plus batch verification and the two bulk-removal flows (account closure and holder removal).
  • Key claims — the BACEN process for taking a key over from another PSP: portability of your own key, or an ownership claim, with both sides of the negotiation exposed.
  • Banks — the national SPI participant catalog, read live from JDPI.
  • Transactions — outbound payments, over SPI (two-phase, asynchronous) or settled on your own book when the payee is on-us, plus the read surface that closes the loop.
  • Refunds — payee-initiated devolution of a payment you received, always a new transaction row capped at the original amount.
  • Limits — per-account outbound transaction limits, seeded by the account’s first outbound payment and enforced before any money moves.
  • QR codes — static and immediate dynamic codes with self-hosted signed payloads, decode, and listing; the anonymous public payload and JWKS routes are documented in that section’s introduction.
  • Webhooks — the inbound mirror JDPI calls on you: cash-in, payee-bank-initiated devolução, and synchronous account validation.
  • Indirect participants — the registry of the institutions that reach SPI through your ISPB: lifecycle, settlement positions, delivery notices, and the reconciliation feed.
  • MED 2.0 — BACEN’s special return mechanism: infraction reports, refund requests in both roles, creator-side value recoveries, and fraud markers; the credit of a refund you won arrives on its own webhook, under MED Inbound Credit.
  • Pix Automático — recurring authorizations, the schedules under them, composite QR codes, and the inbound registration, settlement, and event legs JDPI calls on you.
  • Systemplane — the operator-facing runtime-configuration surface; payment clients never need it. Its routes are documented with the platform, not as a section of this reference.

​
Money: one API, two units

Every money field of this API’s own contract is an int64 count of centavos — 110001 means R$ 1.100,01 — in JSON bodies, query, path, and header alike. Every money field on a body authored by JDPI — the webhook mirrors, the MED inbound credit, and the Pix Automático inbound, settlement, and event routes — is a JSON number in reais (1100.01), because that is JD’s contract on the payloads JD sends; the rail converts to centavos at the boundary. The discriminator is which side authored the body, never the field’s language: Portuguese-named fields on this API’s own write surfaces are still integer centavos. Each field’s description in the reference states its unit.

​
Errors

Errors are RFC 9457 application/problem+json, and every one carries a PIX-XXXX taxonomy code in the code member — match on the code, never on the human-readable text. The status discipline is attribution: a 4xx means the request, or the data the request names, is what failed, and the body names the field or entity; a 5xx names the failing dependency (for example 503 PIX-1050, JDPI temporarily unavailable) rather than hiding behind a generic error. The full catalog, with the exact detail each code carries, is the Pix JD error list.

​
How Pix movements land in Midaz

The direct participation plugin posts every settled Pix movement to Midaz as a ledger transaction. The external leg goes against the clearing account (for example, @external/BRL). Settled movements include cash-out, cash-in, refunds (devolução), MED effectuation legs, and Pix Automático settlement. Midaz records the accounting entry. The payer and payee identity (bank, branch, account, holder name and document, Pix key) lives only in the plugin’s own transaction record. Every BACEN reference lives only in that record. Correlation between the two systems works through identifiers, not metadata:
  • The end-to-end ID (E2E) is the idempotency key of the Midaz posting, so a retried settlement can never double-post to the ledger. Follow-up legs of the same E2E (a devolução or a MED effectuation) derive their key from the E2E with a flow suffix. They never collide with the original posting.
  • The plugin stores the Midaz posting ID on its own transaction record. It uses that ID to commit or cancel the pending debit of a two-phase cash-out.
To see the banking detail behind a ledger entry, query the plugin’s transaction API by the plugin transaction id or the E2E ID. The Midaz transaction itself carries no counterparty data and no custom metadata. The ledger stays pure accounting.

​
Where to start

  1. Setting up the rail — the provisioning chain, in order: the Midaz ledger and CRM records, the twenty accounting routes, the systemplane keys that carry your ISPB, and the check that proves each step landed.
  2. Hosting indirect participants — the three extra provisioning steps for a deployment that settles Pix on behalf of other institutions. Skip it if you settle only your own customers’ Pix.
  3. Environment variables — the deploy-time configuration: JD connectivity, the ledger and CRM endpoints, QR hosting, and the notification providers.
  4. The API reference — pick your domain in the map above; each link lands on a representative operation of its section.
Lerian provisions the provider-specific configuration for direct participation via JD with your integration. To set up direct Pix participation, get in touch with our team.