Process a payee-bank-initiated PIX devolução

Registers a PIX devolução that the PAYEE’s bank initiated and JDPI has already executed (JDPI section 9.3.3). This participant does not initiate it and does not decide it: JDPI pushes it once the return has settled, and this call records the money coming back. It is idempotent on endToEndIdDevolucao: a redelivery of a devolução already registered, carrying the same amount against the same endToEndIdOriginal, answers 200 and credits nothing twice. While the devolução still awaits the original’s settlement (below) that 200 is the acknowledgement the first delivery got; once the credit is booked it names that credit (its idCreditoSgct and dtHrCreditoSgct).

On success the returned amount is credited back to the account that funded the ORIGINAL payment, and the response carries the section 9.3.3 acknowledgement: idReqJdPi, idCreditoSgct (the identifier of the entry this participant recorded) and dtHrCreditoSgct. The original payment is located by endToEndIdOriginal; the payer’s identity and destination are read from the record written when that payment was created, never re-resolved, so a devolução always returns to where the money left from. The one exception is an indirect participant’s payment: its destination is that indirect’s @pi_{ispb} settlement position, read from the indirects registry (below).

A MED devolução (codigoDevolucao BE08 or FR01) is the same call: it credits the same original payer, or, when this engine never made the original payment, the account the recebedor block names, booked on the MED clearing account rather than the ordinary refund one.

WHEN THIS PARTICIPANT NEVER MADE THE ORIGINAL PAYMENT — the account moved here after paying it — the devolução is still credited, because SPI has already settled it. It goes to the account the recebedor block names, resolved exactly as a cash-in to it would be, and books the amount SPI settled; it is neither capped nor parked. This is the only case that reads pagador and recebedor: a devolução of a payment made here never does, so neither block can refuse it.

ONE SUCCESS SHAPE IS NOT A COMPLETED CREDIT, and it is the case an integrator must plan for. When the original payment is still PENDING here (its SPI outcome has not been reconciled yet), the devolução is ACCEPTED AND OWNED rather than credited: it is recorded as awaiting the original’s settlement, the acknowledgement is the same 200 shape with idCreditoSgct naming that record, and a background sweep completes the credit once the original settles. So a 200 asserts this participant has taken responsibility for the devolução, not that the money has already moved.

WHEN THE ORIGINAL PAYMENT BELONGED TO AN INDIRECT PARTICIPANT, the devolução follows it. This participant may serve indirect participants — other institutions registered here with POST /v1/indirects that reach SPI through this participant’s ISPB. A payment originated for one of them was debited from its @pi_{ispb} settlement position, so the return credits that same position and the recorded devolução is stamped with the same institution as the original. Nothing in the section 9.3.3 payload says so — the linkage comes from the original payment’s record, or, when this participant never made that payment, from the recebedor resolved as a cash-in’s would be — and the 200 body is identical either way.

An indirect-linked devolução also queues a NOTICE to that registration’s delivery.endpointUrl: one HTTPS POST forwarding this webhook’s JD 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. It is queued on the same conditions the cash-in notice is, and with the same asymmetry: a queued notice rides the devolução’s own database transaction, but a devolução can be credited and answered 200 with NO notice queued — when this deployment has no outbound queue configured, or when the verbatim JD body could not be retained for forwarding. Delivery of a queued notice is AT-LEAST-ONCE and independent of this 200: it can repeat, and it can fail permanently while the money stays booked. The institution must dedup on endToEndIdDevolucao and read GET /v1/indirects//transactions as the record of truth — which is also the only place a devolução whose notice was never queued becomes visible.

A devolução that CANNOT be registered is answered with an HTTP error carrying a distinct code in the problem body’s code member:

• 409 PIX-0029 - this endToEndIdDevolucao was already registered here for a DIFFERENT devolução: another amount or another endToEndIdOriginal. Nothing was credited for this delivery; the original registration stays unchanged.
• 422 PIX-0030 - the devolução amount is not greater than zero.
• 500 PIX-4011 - whether the credit landed is not settled yet: an earlier delivery of this endToEndIdDevolucao is still being credited, or the ledger could not answer whether its credit landed. Nothing more was credited; redeliver, and the redelivery that finds the credit gets its acknowledgement.
• 503 / 504 - the ledger was unreachable or timed out on the credit. Redeliver: the redelivery adopts a credit that landed rather than posting it twice.
• 400 PIX-0061 - the body failed schema validation at the edge, before any lookup ran.

When this participant never made the original payment, the recebedor can also refuse the credit, with the codes a cash-in to that account would get. Nothing is credited on any of them:

• 400 PIX-0061 - recebedor is missing, is not a participant block, carries a malformed CPF/CNPJ or ISPB, or does not name recebedor.ispb, recebedor.cpfCnpj and recebedor.nrConta.
• 404 PIX-0115 - the account the recebedor names was not found here, or pagador.ispb identifies Bacen (99999).
• 404 PIX-0119 - recebedor.ispb is neither this participant’s own ISPB nor an ACTIVE indirect participant registered in this tenant.
• 409 PIX-0116 - recebedor.cpfCnpj names more than one account here.
• 409 PIX-0117 - the addressed account belongs to a different holder than recebedor.cpfCnpj names.
• 409 PIX-0118 - the addressed account exists here but is not set up to receive credits.
• 500 PIX-0120 - a provisioning fault at this participant; redeliver once it is corrected.

A customer or registry lookup that fails answers 500 with nothing credited, and the devolução is safe to redeliver. For a devolução of a payment made here, none of the refusals are specific to an indirect participant: the linkage is read from the original payment rather than resolved from this request.