Skip to main content
To settle a Pix at the Banco Central, an institution needs a connection to the National Financial System infrastructure. That connection is expensive and slow to get, and not every institution has one. An institution without it uses the connection of another institution. It becomes an indirect participant, and a direct participant settles for it and hosts it. The direct and indirect model explains that arrangement: who holds the settlement account, and where each institution’s money lives. A tenant that hosts indirect participants is a direct participant first. Finish steps 1 to 7 of Setting up the rail exactly as that page says. This page is its step 8 for a deployment that settles Pix for other institutions. If your deployment settles only the Pix of its own customers, skip this page.
Do step 1 before step 3. Without the encryption key, every registration fails. Do step 2 before step 4: with the posture off, the certificate step is refused with 422 PIX-0111. Do step 4 and step 5 after step 3, because both act on the participation that the registration creates. Steps 4 and 5 do not depend on each other.
This page covers provisioning. Indirect participants explains what a hosted participation is, how an inbound credit reaches one, how its lifecycle behaves, and every refusal it can answer.
To give an indirect participant its own Pix JD credential that reaches only its own Pix, see Partners in Pix JD.

​
Step 1: the delivery-secret encryption key

On SaaS, there is nothing to do in this step. Lerian configures the key for your tenant. Go to step 2. The rest of this step applies to a self-hosted deployment.
Why this step exists. When you register an indirect participant, you supply a delivery secret. The plugin signs every notice it sends to that institution’s endpoint with it. It is how the institution knows the notice really came from you. That secret is stored encrypted, and the key that encrypts it does not come from the database. It comes from outside. If the key is not configured, every registration that carries a secret fails. That failure covers the whole write surface of the indirect flow.
The message guarantees that no secret was stored. Encryption fails before any write, so there is no half-created row with a plaintext secret to go and clean up. Fix the key and repeat the POST. That is the whole recovery.
This 409 means “provision it”, not “try again later”. The rail looked for the key and found that it does not exist. Only an operator can add it. A repeat of the call without that change fails the same way. That is why the code is a 409 and says nothing about a retry.Its sibling is 503 PIX-0123, “Indirect delivery key source unavailable”. You get it when the rail could not read the key, because its key source refused or did not answer. The rail then does not know that the key does not exist, because the read did not complete. The response names the dependency that failed, and a retry is the right action. Both codes refuse the registration and store nothing. The pair lets you tell an incomplete setup from an outage.
The plugin starts without the key, and it does not refuse to boot. The process logs a warning at startup and comes up healthy. At startup, nothing tells a deployment that will host indirect participants from one that never registers one. So the symptom arrives on the first registration, not on deploy. If you did not read the startup log, the refusal is your first notice.
Where it lives, and why it is not in the systemplane. This contrast explains where each kind of value belongs on this rail.
Do not put the encryption key in the systemplane. The systemplane is the live configuration plane, readable over the admin API, and that is the right home for everything that is not a secret. Credential material does not go there, and the rail separates the two on purpose.Do not commit it either: not in a versioned .env, not in a values.yaml, not in a compose file.
The format: exactly 64 hex characters. It is an AES-256 key (32 bytes), hex-encoded. That is 64 hex characters, not 63 and not 65.
Generate one per deployment. Do not copy another environment’s key and do not reuse another service’s.
An absent, blank, or malformed value all produce the same 409 PIX-0107. There is no default and no degradation to storing the secret in the clear. That is deliberate: a silent default here would store customer secrets encrypted with a key everybody knows.
On a self-hosted deployment, set the deployment variable:
That placeholder is deliberately not a valid key. Pasted as-is, it fails closed with the refusal above. It does not encrypt your customers’ secrets with a value published on a documentation page. The plugin reads the key at startup, so a change needs a process restart. The ISPB binding is different: the plugin reads it on every call, and a change takes effect without a restart.
Do not type the value on a command line. It ends up in your shell history and in CI logs. Read it from a vault, or type it with read -rs, which does not echo.
How to check it landed. No route reads the key back, because it is a secret. There are two signals. The startup log. With the key resolvable, the “key unavailable” warning does not appear. If it does appear, no registration carrying a secret will pass. The behavior. Register an indirect participant. The response changes from 409 PIX-0107 to 201.
Think before you use the behavioral check. A registration is permanent. There is no delete route, and the only exit is close, which keeps the row and holds the ISPB. In a production environment, do not use a throwaway registration to test the key. Use an ISPB that you plan to operate. The startup log saves you that cost.

​
Step 2: declare that this tenant hosts indirect participants

Set plugin-br-pix-jd.indirects/enabled to true. This is a configuration write, so it needs Plugin PIX JD Editor.
The plugin answers 204 when it accepts the value. The value is a JSON boolean, without quotes: {"value":"true"} answers 400. Registration works with the posture off, so you can register participants before you enable it. The posture gates the money paths and the own QR certificate of step 4. With the posture off, step 4 answers 422 PIX-0111. Before you register anyone shows what each half does.
The read fails closed. When a money path “goes back to direct behavior” and nobody changed the key, this is the cause. Look at the systemplane.

​
Step 3: register an indirect participant

One call does the whole assembly. It checks the ISPB, creates the @pi_{ispb} settlement account in Midaz, and marks the participation active. It needs Plugin PIX JD Contributor or Plugin PIX JD Editor.
A 201 means that the participation is ready to use. The status is always ACTIVE. You do not need to poll.
Do not write an indirect participant’s ISPB into tenancy/jd_integration_binding. That key is the identity that the plugin presents to JD. A third party’s ISPB there makes the plugin introduce itself as another institution. Nothing warns you: the plugin accepts 8 valid digits, and the write answers 204. The key is one per tenant, not one per indirect participant. Every indirect participant that you host reaches the SPI through your ISPB.
Registration is permanent. There is no DELETE on /v1/indirects, and CLOSED is terminal. A mistaken registration in a live tenant stays there. Its ISPB stays held against the uniqueness rule until somebody closes it. Check the name, the ISPB, and the endpoint before you call. Rehearse on a disposable environment.
Indirect participants has the refusals, the lifecycle actions, and how to read the registry back.

​
Step 4: configure its own QR certificate, if it has one

Skip this step for an indirect participant that has no QR certificate of its own at JD. Its dynamic QR codes are then signed with your certificate and served on your host, as for your own customers. Why this step exists. Some indirect participants have their own QR certificate at JD. JD then signs their dynamic QR codes with that certificate. The payer’s app checks the signature against the key set that it finds on the same host as the QR payload. So the payload and the key set of that participant must be on the participant’s own host, not on yours. Access: Plugin PIX JD Contributor or Plugin PIX JD Editor.
1

Name the participant's host

Send PATCH /v1/indirects/{indirectId} with the indirectId from the registration:
The 77-character budget. JD caps the URL of a QR payload at 77 characters. The plugin builds it as publicBaseUrl, then QRCODE_PAYLOAD_PATH, then, on SaaS, your institution’s 8-digit ISPB, then the type of the charge and an identifier of up to 22 characters. With the default QRCODE_PAYLOAD_PATH, qr, 37 characters are left for the host. A deployment with a longer QRCODE_PAYLOAD_PATH leaves fewer. Then each dynamic QR code for this participant answers 422 PIX-0112. Choose the host against that budget before you register it.A 200 returns the participation. Check that qrCertificate.ownCertificate is true and qrCertificate.publicBaseUrl is the host that you sent.
2

Publish the participant's key set on its host

The participant cannot make its key set itself, because JD holds the certificate and signs. Read the key set from the plugin:
The answer is an application/jwk-set+json document. Serve those bytes as they are, with that media type, at https:// plus the participant’s host plus / plus QRCODE_JWK_PATH. With the default QRCODE_JWK_PATH, that is https://pix.indirect.example.com/v1/qrcodes/jwks. On SaaS, the path ends with one more segment: your institution’s 8-digit ISPB, for example https://pix.indirect.example.com/v1/qrcodes/jwks/12345678. Read the key set again each time JD rotates the participant’s certificate.The X-JWK-Set-Freshness header says fresh or stale. stale means that JD did not answer and the plugin served its last copy. Read it again before you publish.
The payloads go to the participant’s host too. When you create a dynamic QR code with this participant’s indirectId, the plugin does not serve its payload. The response carries payloadJws, and the participant serves it at payloadUrl on its own host. Create a dynamic QR code describes that response, and how to recover a payload that you did not receive.

​
Step 5: fund the position

The registration creates the @pi_{ispb} account empty. Inbound Pix credits it, but an outbound payment needs balance first. Without funds, every payment that leaves through that indirect participant fails for insufficient balance. You make the initial load. It mirrors the arrangement: at JD you administer that institution’s limit, and in your ledger you load its position. The mechanics are the same as the funding step of Setting up the rail. Post a Midaz transaction from @external/BRL, with the same variables as that page. Only the destination changes, to the piAccountAlias from the registration. It is a Midaz transaction, so it needs Midaz Editor or Midaz Contributor.
If you lose the response to a top-up, send the exact same body again within 300 seconds. Midaz then posts it once. After that window, check the position balance before you send the top-up again.Change the description only for a new top-up. A new description on a real retry adds a second credit by mistake.
The position also controls the participation’s exit. The plugin refuses close with 409 PIX-0096 while the @pi account holds funds, available or on hold, and names the cause. Bring the position to zero before you close. A funded position keeps the participation open until you do. How to check. Read the account’s balance back in Midaz. The surest check is behavior: an outbound payment through the indirect participant stops its refusals for insufficient balance.

​
Return a Pix that an indirect participant received

A Pix for a customer of an indirect participant lands on that participant’s @pi_{ispb} position. To return it, send POST /v1/refunds with the indirectId of that participant. The devolução then debits that position. The plugin refuses the devolução with 422 PIX-0135 in three cases, and moves no money:
  • the original Pix landed on an indirect participant’s position, and the refund has no indirectId.
  • the refund names another indirect participant.
  • the original Pix landed on a direct account, and the refund has an indirectId.
The indirectId passes the same checks as on a payment order. The hosting posture must be on, and the participation must be ACTIVE.

​
The systemplane keys of the indirects namespace

There are five keys, all in plugin-br-pix-jd.indirects, and all of them always exist. The three delivery and resolution keys take effect only when enabled is true, because they tune the money paths. validate_ispb_on_jd is the exception. It gates a step of registration, which works while enabled is still false.
The plugin answers 204 when it accepts a value and 400 when the validator refuses it. Booleans and integers go without quotes. A value outside the range answers 400. The plugin does not clamp it.
The two steps that can stop the indirect flow on their own are not in this namespace. Identity is the systemplane key tenancy/jd_integration_binding. Without it, every payment fails with 409 PIX-0092. The encryption key comes from a deployment variable or a secret store. Without it, every registration fails with 409 PIX-0107.