Skip to main content
This page is for the team of each engine that works behind the Courier: your existing core and the Lerian stack. An operator first registers the engine in the Courier, through the engine API. The registration holds the participant ISPBs of the engine, its first credential, and the addresses where the engine receives Pix calls and cross-core TEDs.

SPB: point the engine at the Courier


On the SPB rail, the Courier serves the same SOAP interface as JD. An engine that already talks to JD changes the address and the channel credential. It keeps its messages and its calls. The spb-sender role serves the interface at the path /soap, on its own port (default 8081). It accepts the four JD operations: Each engine signs in to the Courier’s SOAP address with its own channel credential, not with your JD credential. An operator issues the credential through the Courier API. The response shows the password once. Store it then. When you issue a new credential for the same engine, the previous one keeps working for an overlap window (24 hours by default), then stops. An operator can revoke a credential at any time. The Courier forwards each send to JD with your JD credential. A refused sign-in gets 401 with no body.

Before the engine changes its address

  1. Clear the reconciliation backlog of the engine against JD. The Courier answers a query only for the sends and messages that passed through it. A query about an earlier send receives 503.
  2. Ask the operator to issue the channel credential of the engine.
  3. Change the JD address and credential of the engine to the values of the Courier.

What the engine receives

A redelivered message keeps its original sequence number (NumCabSeq). The engine must accept a repeated sequence number as a repeat, not as a new message. The Courier gives these answers to EnviaMensagem: After an indeterminate send, query the control number with ConsultaNumCtrlIF. A final answer of JD settles the send in the journal. Do not send the message again with the same control number: the Courier refuses it. When every earlier send of the control number has the outcome NOT_SENT, the Courier answers the query with the JD code ALN01, and it does not forward the query.

Pix: receive the calls of JD


On the Pix rail, the Courier delivers each inbound call to the Pix address of the owner engine. The engine serves the same paths that JD calls, for the account validation, the cash-in, the refund, and the Pix Automático calls. For an asynchronous account validation, the engine receives its share of the credits at /v1/webhooks/validates/async.

How the Courier calls the engine

  • The Courier appends the path of the JD call to the Pix address of the engine. It uses the same method.
  • The body is the body that JD sent, byte for byte.
  • The Courier forwards these headers when JD sends them: Chave-Idempotencia, X-DataHoraEvento, X-NomeEvento, and Content-Type.
  • The Courier waits up to 60 seconds for the answer. It reads up to 1 MiB of the answer.
  • The Courier does not follow redirects.
To deliver Pix messages, the Courier calls the Pix address you register for each engine. Register a credential for every engine: the Courier then sends an Access Manager token with each call. Without a credential, the Courier calls the engine without authentication. In production, use an https address. Registering a Pix address requires the pix-delivery:write permission. The engine’s client ID and secret live in AWS Secrets Manager. See Engine credentials.

How the Courier reads the answer

The Courier relays the answer of the engine to JD. For a message, the status decides what happens next: A status from the last row is final. To have JD send the message again, answer with a status from the first row. The engine can receive the same message more than once. For example, the Courier calls the engine again after a timeout. Use the identifiers that JD sends, such as Chave-Idempotencia, to recognize a repeat.

Pix: send calls to JD through the Courier


When you turn on the Pix transit, an engine sends its Pix calls to JD through the Courier, on the JDPI paths that it uses with JD. The Courier calls JD with the SPI cabin credential of your institution.
  1. Ask the operator to issue the Pix transit credential of the engine. The response shows the secret once. Store it then.
  2. Change the JDPI address of the engine to the address of the transit.
  3. The engine requests its token at the JDPI token path of the transit, with the client ID and secret of that credential. The Courier answers the token request itself.
When you issue a new Pix transit credential for the same engine, the previous one keeps working for the overlap window, then stops. An operator can revoke a credential at any time, and its tokens stop at once. Outside the account validation result, the Courier writes only these answers itself: the token, a 401 with no body for a refused credential, a 404 with no body for a path outside the JDPI paths, and a 503 with X-Send-Outcome: not-sent. That 503 means that nothing reached JD, and the engine can release its hold. Every other answer, a 503 from JD included, comes back as JD wrote it. When the request may have reached JD and the answer of JD is lost, the Courier closes the connection without an answer. Treat that outcome as unknown, and reconcile it before you release anything. No proxy between the engine and the JD Courier may retry a 503. On the account validation result, the Courier can also answer 409 JDC-0503: the credit already has a different result, and the first one stands. A 503 JDC-9001 there means that JD gave no verdict or the Courier could not relay the result: send the same result again with the same Chave-Idempotencia.

Calls the engine makes to the Courier


The admin role serves the operations that the engines call: the ownership lookup, the claims, the leg declarations, and the cross-core relay. Each engine calls these operations with an Access Manager application that the operator binds to the engine. One engine can hold several applications, one for each product that calls the Courier. An example is the Pix plugin and the TED plugin of the Lerian stack. The operator registers the first application with the engine and binds each other one. An application belongs to one engine only. It needs the ownership:read permission for the lookup, ownership:write for the claims and the leg declarations, and cross-core:send for the cross-core relay. The Courier answers 401 to any other caller. When the engine is Pix via JD, its worker claims its recurrences on the Courier, on the side of the payer or of the charger, and the CNPJ of each charger that it serves. Before the Courier starts to receive Pix, an operator calls its Courier ownership route (POST /v1/pix-automatico/courier-ownership). The route claims the recurrences that already exist and declares the legs of the payments in progress. See Claims on the Courier.

Ownership lookup

Before the engine settles a payment inside your institution, it must know which engine owns the destination. Call the ownership lookup with the key as you hold it. The answer tells if the key has an owner, and if that owner is the engine that made the call. The answer is authoritative:
  • 200 with resolved: true names the owner.
  • 200 with resolved: false means that no engine of your institution owns the key.
  • 422 means that the key is not valid.
  • Treat any other status as a refusal: fail the payment and do not settle it inside your institution.

Account and document claims

Claim each account that the engine opens, when it opens it. Before the cutover, claim in the same way the accounts that the engine already holds, up to 1000 keys in each call. The same call claims the CNPJ of each Pix Automático charger that the engine serves (DOCUMENT) and the side of the charger of each recurrence (PIX_RECURRENCE_ID_CHARGER).
  • Claim a payment account without a branch. A payment account claimed with a branch is a key that routing never reads.
  • The answer gives one result for each key, in the order of the request: CLAIMED, ALREADY_OWNED, HELD_ELSEWHERE, or INVALID. Report each HELD_ELSEWHERE to an operator: only an operator moves a key.
  • After a 503 or a lost answer, send the same call again. The claim is idempotent.

Pix Automático recurrence claim

When the engine authorizes a Pix Automático recurrence, it claims the recurrence on the side of the payer. The Courier then routes the schedule calls of that recurrence to the engine. The claim is idempotent. A recurrence that another engine holds receives 409 JDC-0102. Only an operator can move it. Before the Courier starts to receive Pix, each engine claims the recurrences that already exist. A schedule message for a recurrence without an owner stays retained until the claim arrives. A schedule validation for that recurrence receives 503.

Pix Automático leg declaration

Some Pix Automático calls follow an earlier leg of the same payment. See Which key routes each call. Before the Courier starts to receive Pix, each engine declares the legs it holds for the payments in progress:
  • block: each debit block that the engine accepted, when the debit or its reversal has not arrived yet.
  • schedule: each schedule whose debit, reversal, or cancellation status has not arrived yet. Without an accepted block, the debit and its reversal follow the schedule.
A call that arrives before its leg is declared stays retained. The Courier releases it after the declaration. A declaration that conflicts with the record of the Courier receives 409 JDC-0116. Stop and report it to an operator.

Cross-core relay


Two engines of your institution can share one ISPB. A payment from an account of one engine to an account of the other engine does not go to the STR or to the SPI. The paying engine sends it to the owner engine through the Courier. The Courier relays four kinds of payment: Bank Transfer does not return a TED that it received through the relay. For the Bank Transfer side, see Cross-core transfers. Each engine follows the contract below, the other core of your institution included.

Receive a cross-core payment

  1. Ask the operator to register the TED address (tedDelivery) and the Pix address (pixDelivery) of the engine. Setting them requires the ted-delivery:write and pix-delivery:write permissions.
  2. Serve the paths in the table. The Courier sends the body of the paying engine byte for byte. It also sends Content-Type, Chave-Idempotencia when the paying engine sends it, and X-Courier-Origin-Engine with the ID of the paying engine. When the address has a credential, the Courier sends an Access Manager token.
  3. Answer with a 2xx status when you credit the payee. The Courier relays your answer to the paying engine as you wrote it.
The Courier makes one attempt and waits up to 15 seconds. The Courier treats a redirect, a 401, and a 403 from your address as a call that you did not take. The paying engine sends the same bytes again while its outcome is unknown, so credit each payment once.

Send a cross-core payment

  1. Call the ownership lookup for the account of the payee. Send the payment through the relay only when another engine owns the account.
  2. Call the relay path with an engine application that has the cross-core:send permission. Send the header X-Courier-Expected-Owner with the engine ID that the lookup returned.
  3. Put the account of the payee in the body. On TED, the Courier reads payee.branch, payee.account, and payee.accountType (PG for a payment account, with no branch). On Pix, it reads recebedor.nrAgencia, recebedor.nrConta, and recebedor.tpConta (3 for a payment account, with no branch).
The Courier relays the call only when the map names the engine in X-Courier-Expected-Owner. Read its answer this way: Treat X-Send-Outcome: not-sent as not sent. It is about this call only. When an earlier attempt of the same payment had an unknown outcome, keep the hold: send the same bytes again, or stop for an operator after 409 JDC-0119.