Create a PIX transaction

Creates an outbound PIX payment. What happens next depends on where the payee is, and the two branches answer with different statuses and different bodies — a client has to handle both.

An on-us payee (payee.ispb equal to this participant’s own ISPB, on a direct order) settles SYNCHRONOUSLY as an INTRA_PSP ledger transfer and answers 201 with the transaction already EXECUTED. Any other payee settles over SPI in TWO PHASES: the amount is first HELD on the paying position as a pending ledger debit, and only then is the order submitted to JDPI (§8.4.1), which is asynchronous by design — nothing has settled when the call returns. A direct order answers 201 with the transaction PENDING; an order routed through a registered indirect (indirectId in the body) answers 202 carrying JD’s own §8.4.1 acknowledgement byte-for-byte, whose idReqJdPi is the handle the outcome is read with. Either way, poll GET /v1/transactions/: a background reconciler consults JDPI §8.4.2 and then commits or cancels the hold, and the money is not settled until the status says so.

WHAT indirectId ACTUALLY MOVES, because it is more than a label. This participant may serve INDIRECT participants — other institutions registered here with POST /v1/indirects that reach SPI through this participant’s ISPB. Naming one on an order changes THREE things at once: the amount is held on that institution’s @pi_{ispb} settlement position instead of on the payer’s own, the persisted order is stamped with that institution so it appears in GET /v1/indirects//transactions, and the response shape changes from 201-plus-plugin-body to 202-plus-JD-body. The identifier is ROUTING DATA, not a credential: this participant authenticates you, and guaranteeing that the order really belongs to that institution is your responsibility, not this API’s.

⚠️ indirectId IS SILENTLY IGNORED WHILE THIS TENANT’S INDIRECT-PARTICIPANTS FEATURE IS SWITCHED OFF. With the feature off the value is not parsed, not resolved and not refused: the order runs as a DIRECT one, holding the amount on the direct participant’s own position and answering 201. Nothing in the response says the routing was dropped. Confirm the feature is on before sending the first order for an institution — an unknown id answering 404 PIX-0095 is the evidence that it is.

When the order reaches its outcome, an indirect order may ALSO push a NOTICE to the endpoint that registration carries (delivery.endpointUrl), queued by the background reconciler once JD’s terminal outcome is known — an HTTPS POST forwarding JD’s own result body verbatim, carrying X-Lerian-Signature (‘sha256=’ followed by the hex HMAC-SHA256 of the exact body bytes under the registration’s shared secret) and X-Lerian-Timestamp. Do not build on the notice arriving. No notice is queued at all when this deployment has no outbound queue configured, and none is queued when the outcome carries no JD result body to forward — an order cancelled locally, without a JD answer, is exactly that case. Delivery of a notice that WAS queued is AT-LEAST-ONCE and can still fail permanently while the payment stands. So the institution must dedup on the end-to-end id and treat GET /v1/indirects//transactions, not the notice, as the record of truth: it is the only place an outcome whose notice was never queued becomes visible. A direct order pushes no notice at all.

End-to-end ids: send endToEndId only when you already hold one (from a key lookup or a QR decode), and then payee.key is mandatory with it. Omit it on a manually typed order and SPI mints one — the response carries the minted value. Idempotency: the optional clientRequestId is the only identifier that exists BEFORE the JD call, so it is what makes a retry safe on every branch, and it is the ONLY protection a manually typed order has (that order’s end-to-end id does not exist yet when the retry arrives). Amounts are integer centavos.

Every refusal below is decided before the hold is taken, so it moves ZERO money; when JDPI rejects the order after the hold exists, the hold is released and nothing is persisted. Refusals: 409 PIX-0029 when this endToEndId or clientRequestId was already used; 409 PIX-0076 when the paying position lacks the amount; 409 PIX-0078 on a transfer to the same account; 409 PIX-0032 when the account’s period limit is exceeded; 422 PIX-0030 on a non-positive amount; 422 PIX-0037 when endToEndId arrives without payee.key; 422 PIX-0108 when the payer — or, on an indirect order, the indirect’s @pi — resolves in the CRM but is not bound to a ledger account; 404 PIX-0095 for an unknown or malformed indirectId and 422 PIX-0100 when the indirect it names is not ACTIVE; 422 PIX-0102 when a payer.ispb is supplied on an indirect order and disagrees with that indirect’s own ISPB; 400 PIX-0061 when accountId is empty or an accountType is outside the PIX domain 0..4. On an indirect order a JD business rejection is passed back with JD’s own status and body instead of a problem+json.