The ownership map
The ownership map is a list of keys. Each key has one owner engine. An operator creates and changes the map through the ownership API. The Courier refuses a second owner for a key with
409 JDC-0102. To change the owner, the operator moves the key.
The map accepts seven kinds of key:
The kinds that inbound routing does not use are available to the engines through the ownership lookup. An engine uses the lookup to find out if another engine owns the destination of a payment.
The Courier normalizes each key value. For example, it removes the punctuation from a CPF and the leading zeros from a branch. Send the value as you hold it.
Every change to the map writes an entry in the audit history of the key, in the same transaction. The entry records who made the change, when, the previous owner, and the new owner. A move also records its reason. You can read the history of a key after its removal, through the audit lookup by key.
Routing on the SPB rail
The
spb-consumer role reads the SPB messages that JD holds for your institution. The Courier stores each message before it decides the route. Then it applies these rules, in order:
- Send journal. When the control number (
NumCtrlIF) of the message matches a send in the send journal, the message goes to the engine that made the send. This rule routes the replies to messages that an engine sent. - Ownership map. The Courier reads the credited account of the message: branch and account, or the payment account. When the map has an owner for that account, the message goes to the owner.
- Delivery mode. When the map has no owner, the Courier reads the delivery mode declared for the message code. This rule never applies to the money codes
STR0008,STR0008R1,STR0008R2,STR0010,STR0010R1, andSTR0010R2. - Retention. When no rule decides, the Courier retains the message.
DELIVERY_FAILED.
The Courier does not push SPB messages to the engines. Each engine asks the Courier for its messages through the same SOAP interface it uses with JD. The Courier answers with the oldest message that waits for that engine. For details, see Connecting an engine.
Delivery modes
A delivery mode applies to one SPB message code. An operator declares it with a reason. There are two modes:ALL_ENGINES: the message goes to every enabled engine.REFUSE: the message goes to no engine. The Courier keeps it, with the stateREFUSED.
422 JDC-0110. A revoked declaration stays readable as history. The Pix rail accepts no declaration.
Redelivery
An operator can serve an SPB message again to one of the engines that the message was routed to. The Courier does not ask JD again. The next request of the engine receives the stored message, with its original sequence number. Your operator gives a reason, and the Courier records it.Bypass
A bypass is the state where one engine connects to JD directly again, outside the Courier. An operator declares a bypass on the SPB rail with the engine and a reason. While a bypass is active, the Courier does not read from JD on that rail. It also does not route or re-check SPB messages. A reconciliation cycle that runs during a bypass lists the suspended guarantees. At most one engine can be in bypass on a rail. The Pix rail has no bypass.Routing on the Pix rail
JD sends the inbound Pix calls of your institution to the address that the
pix-ingress role serves. The Courier decides the owner during the call, delivers the call to the engine, and relays the answer of the engine to JD.
JD makes two kinds of call:
- Questions. JD waits for an answer before it continues: account validation, the Pix Automático debit block, and the authorization and schedule validations. The Courier does not retain a question.
- Messages. JD reports a fact: cash-in, refund (devolução), and the Pix Automático registrations, settlements, and events. The Courier can retain a message.
Which key routes each call
Your ISPBs are the participant ISPBs that the operator registers on the engines.
The Pix Automático calls that follow an earlier leg need a record of that leg. The Courier records the earlier legs that it delivers. For the payments in progress before the Courier receives Pix, each engine declares its legs. See Connecting an engine.
What JD receives
When the engine answers a message with a
5xx, 408, or 429 status, the Courier relays that answer to JD and retains the message. The next resend of JD reaches the engine again. When the engine answers with a 3xx, 401, or 403 status, or does not answer, JD receives 503 and the Courier retains the message.
Retained messages
A retained message stays in the Courier database with its reason. The Courier does not credit it, return it to BACEN, or delete it. Your operator lists the retained messages, oldest first, through the retained API. The list shows the reason and the times. It does not show the content of the message.
How a retained message leaves
The Courier re-checks each retained message with a routing or delivery cause, at most once a minute. When the cause clears, the message leaves by itself. For example, an operator assigns the account, or enables the owner engine again. On Pix, a resend of JD also runs the decision again. An operator can also request a re-evaluation with a reason. The Courier records who asked, when, and why, and re-checks the message first. The re-evaluation runs the same routing rules as a new message. The operator never chooses the engine. The Courier refuses a re-evaluation for the reasonCLASSIFICATION_FAILED with 422 JDC-0204.
When the Courier releases a Pix message, JD is not in the call. The Courier stores the answer of the engine and gives it to JD at the next resend.
Sends to JD and the send journal
Engines send their SPB messages to JD through the
spb-sender role. The Courier writes each send in the send journal before the send leaves. Then it sends the message to JD once and relays the answer of JD to the engine. The Courier never sends a message again by itself.
The send journal records one of these outcomes for each send:
The Courier accepts each control number once for each tenant. A send with the outcome
NOT_SENT does not count. A second send of the same control number does not reach JD.
An indeterminate send gets its answer when the engine queries JD about it through the Courier. To handle the indeterminate sends that remain, see Daily operations.