Reversos (Brasil)
POST /v1/br/payin/pix/{txId}/reversal
Devuelve al pagador todo o parte de un cobro Pix COMPLETED. Cada reverso es una transacción nueva enlazada al cobro: el cobro original sigue COMPLETED y acumula cuánto se ha devuelto. Puedes hacer varios reversos parciales hasta devolver el monto total.
Saldo necesario
Sección titulada «Saldo necesario»Se devuelve el monto bruto al pagador, así que necesitas ese monto disponible en tu saldo. Ejemplo: un cobro de R$ 3,00 con R$ 0,04 de comisión te acreditó R$ 2,96; para devolver los R$ 3,00 necesitas R$ 3,00 disponibles. Al crear el reverso se retiene el monto; cuando la red confirma se debita (y si falla se libera). Las comisiones del cobro no se devuelven y el reverso no cobra comisión.
Request body
Sección titulada «Request body»{ "amount": 100, "reason": "customerRequest", "description": "Devolución parcial pedido 77", "reference": "DEV-77-1"}| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
reason | string | ✅ | customerRequest, bankError, fraud, cashierError |
amount | number | ❌ | Centavos, entero > 0. Si se omite, se devuelve todo lo que queda por reversar |
description | string | ❌ | Hasta 140 caracteres |
reference | string | ❌ | Tu referencia interna del reverso; vuelve en el webhook como reference |
Response 201 Created
Sección titulada «Response 201 Created»{ "txId": "5f0b6c1e-2a7d-4c8e-9b1a-3e4d5f6a7b8c", "originalTxId": "50580a1772734a7fa094638bf7b724ce", "reference": "DEV-77-1", "status": "PROCESSING", "amount": 100, "currency": "BRL", "reason": "customerRequest", "e2eId": "D17028875202610061753012739ec30b", "remainingAmount": 200, "createdAt": "2026-10-06T17:53:00.000Z"}El resultado final llega por webhook payin.reversed (status COMPLETED o FAILED).
Errores
Sección titulada «Errores»| HTTP | code | Cuándo |
|---|---|---|
400 | — | reason inválido o amount no es entero positivo |
400 | IDEMPOTENCY_KEY_REQUIRED | Falta X-Idempotency-Key |
402 | INSUFFICIENT_BALANCE | Tu saldo disponible no cubre el monto (availableBalance, requiredAmount) |
404 | — | El cobro no existe o no es tuyo |
409 | NOT_REVERSIBLE | El cobro no está COMPLETED, no tiene e2eId o es él mismo un reverso |
409 | ALREADY_FULLY_REVERSED | Ya se devolvió todo el cobro |
422 | REVERSAL_EXCEEDS_REMAINING | amount supera lo que queda (remainingAmount) |
422 | PROVIDER_REJECTED | La red rechazó el reverso; no se retuvo saldo |
502 | — | Respuesta ambigua del proveedor: el reverso puede haberse ejecutado. No reintentes con otra X-Idempotency-Key; el resultado llega por webhook |
Payouts devueltos por el banco destino
Sección titulada «Payouts devueltos por el banco destino»Un pago enviado no se revierte por API: si el banco destino lo devuelve, se registra automáticamente como una transacción de reverso (sentido IN), se te acredita el monto devuelto y recibes payout.reversed. El payout original sigue COMPLETED.
Consulta
Sección titulada «Consulta»GET /v1/br/payin/pix/{txId} y GET /v1/br/payout/pix/{externalId} incluyen, en la transacción original, reversed, reversalState (PARTIAL | FULL), reversedAmount, remainingAmount y reversals[]; y en una transacción de reverso, isReversal, reversalOfTxId y originalTx.
Ver el payload en Webhooks.