Create a PIX refund

Creates a PIX refund (devolução) 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 devolucao 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. 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 devolucao 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 devolução 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 devolução 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 devolução); a new devolução 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.

Refusals: 422 PIX-0036 when no EXECUTED payment matches that (endToEndId, transactionId) pair, which is also the answer when the pair names a devolução (a devolução is never the original of another); 400 PIX-0087 when the original is a payment sent to another institution 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, names another indirect, or is sent for a Pix received on a direct account; 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 devolucao debits (the indirect’s position, for a Pix it received) is below the amount of a devolucao sent over SPI (nothing is reserved or sent); 409 PIX-0029 when this X-Idempotency key already names a devolução of the payer, and while another devolucao of the same payment sent over SPI is still PENDING, or when JD answers with an earlier devolucao of it; 422 PIX-0030 on a non-positive amount; 409 PIX-0105 when a ledger the devolucao has to post in does not declare the reversal accounting routes (nothing is posted and no refund is recorded); 500 PIX-0120 when the (organization, ledger) the original was booked in is not one this deployment declares (its body is scrubbed, but the code names the cause: the tenant’s organization catalog needs fixing, not the request); 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.