Create a PIX refund

Creates a PIX refund against an executed transaction. Bacen makes the refund the RECIPIENT’s operation, so the caller must be the party that RECEIVED the original payment: the requesting accountId’s document has to equal the original payee’s document. The original payer cannot refund a payment it sent — that is the MED/fraud path, not this one.

Identify the original with BOTH transactionId (the local UUID) and endToEndId, and it must still be EXECUTED. Partial refunds are allowed and they ACCUMULATE: the amount is checked against the original amount minus everything already refunded, under a row lock on the original, so two concurrent refunds cannot together exceed it. An on-us original is refunded as a synchronous ledger reversal from the refunder to the original payer; a payment received from another institution is returned over SPI: the amount is first reserved on the refunding account, then the refund is submitted to JDPI, and it answers PENDING with the money held until SPI settles it (EXECUTED, the reserve committed) or refuses it (ERROR, the reserve released) — poll GET /v1/transactions. A Pix received from an account that banks at this participant but is held in other books is returned to those books, never over SPI: the amount is held on the refunding account and the refund relayed, answering EXECUTED once those books credited the original payer, PENDING while their answer is unknown (the reconcile worker completes it — poll GET /v1/transactions), 422 PIX-0145 when they refused it and 503 PIX-0146 when they could not be reached; both release the hold, so nothing moved; 409 PIX-0149 when any fee in the package priced on the cross-core return route (this refund to the other core of the same participant, priced like a refund sent to another bank) is configured to deduct from the amount instead of being charged on top (an operator setting) — the applied package is known only once the hold is posted, so this refusal comes after the hold and before anything is relayed: the hold is released, by the reconcile worker when the ledger does not confirm the release at once, and nothing moved. The refund’s own end-to-end id (endToEndRefundId) is filled when JD supplies it and may be empty while the refund is PENDING; an empty value is not a failure, the outcome arrives as transaction.refunded or transaction.failed. An on-us original that itself moved between two ledgers of this institution is returned the same way it was paid — a reserve in the ledger that received it, a credit in the ledger that paid, then a commit — so that one branch reports EXECUTED only after both legs landed; a refund whose credit that ledger has not yet confirmed delivered is ACCEPTED and still settling, reported PENDING with the money held, and the reconcile worker completes it — poll GET /v1/transactions rather than retrying it as a fresh refund. The exception is the same one the payment route carries: once the credit has landed, a settlement outcome the ledger leaves unknown while CLOSING the reserve still answers 5xx and still leaves the transaction PENDING, so a 5xx here never means nothing happened — poll it rather than sending a new refund under a new key. code is the return reason and is accepted only as BE08, FR01, MD06 or SL02.

Idempotency: the X-Idempotency header is REQUIRED, and it is what makes a resend safe on every branch, on-us included: once a refund is recorded under a key, a resend under that key is refused 409 PIX-0029 and moves no money — read its outcome with GET /v1/transactions. Keys are scoped to the payer (the organization, plus the indirect participant on an indirect refund); a new refund needs a new key.

A Pix received on an indirect participant’s PIX position is returned by that indirect: send its indirectId, and the refund debits that indirect’s position. A Pix received on a direct account is returned without one.

payerIspb optionally names the direct participant paying the refund back. Named, the original has to be booked in that participant’s books, checked before the idempotency key is read and before anything is held or sent; a token confined to one participant has to name it.

Refusals: 422 PIX-0036 when no EXECUTED payment matches that (endToEndId, transactionId) pair, which is also the answer when the pair names a refund (a refund is never the original of another); 404 PIX-0147 when payerIspb names a participant, or indirectId an indirect, that does not hold the original (checked before eligibility, so it never tells the caller whether another participant’s original exists or which way it went); 422 PIX-0128 for a payerIspb this deployment does not act as; 400 PIX-0087 when the original is a payment sent to another institution, or to an account held in other books of this one, and the caller is its sender; 400 PIX-0089 when it is such a payment and the caller is anyone else (only the receiving institution can return what it received); 400 PIX-0088 when the original is any other payment and the caller is not its payee; 422 PIX-0135 when indirectId is absent on a Pix received on an indirect’s position; 422 PIX-0111 when the indirect-participants feature is off, 404 PIX-0095 when the indirect is not registered and 422 PIX-0100 when it is not ACTIVE, as on a payment order; 409 PIX-0075 when this amount plus the prior refunds would exceed the original; 409 PIX-0076 when the available balance of the account the refund debits (the indirect’s position, for a Pix it received) is below the amount of a refund sent over SPI or to other books (nothing is reserved or sent); 409 PIX-0029 when this X-Idempotency key already names a refund of the payer, and while another refund of the same payment sent over SPI or to other books is still PENDING, or when JD answers with an earlier refund of it; 422 PIX-0030 on a non-positive amount; 409 PIX-0105 when a ledger the refund has to post in does not declare the reversal accounting routes (nothing is posted and no refund is recorded); 409 PIX-0142 when the ledger the original was booked in — or, for an on-us payment between two ledgers, the ledger it was credited in — is no longer configured for Pix on this deployment (nothing is posted and no refund is recorded; an operator has to restore that ledger to the Pix setup); 400 PIX-0061 when the X-Idempotency header is absent, blank or over 255 bytes, accountId or endToEndId is empty, transactionId is not a UUID, or code is outside the four accepted values.