Process a payee-bank-initiated Pix devolução
Processes a payee-bank-initiated Pix devolução pushed by the upstream system; this endpoint does not initiate the return. Credits the original payer the returned amount, subject to a cumulative limit on returned amounts, dedups on the upstream-assigned return end-to-end id, and returns the settlement-gateway credit acknowledgement.
Authorizations
JWT Bearer token authentication. Obtain token from /v1/login/oauth/access_token endpoint
using client credentials (clientId and clientSecret).
Include token in Authorization header:
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Token expires after 3600 seconds (1 hour).
Body
Upstream-assigned return id (idempotency + dedup key).
End-to-end id of the original CASH_OUT.
Upstream request id (GUID), echoed on the acknowledgement.
Return amount in reais (a JSON number).
Return reason code (eRefundCode).
Free-text inter-client info.
Free-text return reason.
Response
OK
settlement-gateway credit timestamp (ISO-8601).
Validation timestamp (ISO-8601).
settlement-gateway credit id.
Echoed upstream request id.
Reason code (on a rejected return).
Reason complement.
Validation result (0=Inválido, 1=Válido).

