Ir al contenido

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.

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.

{
"amount": 100,
"reason": "customerRequest",
"description": "Devolución parcial pedido 77",
"reference": "DEV-77-1"
}
CampoTipoRequeridoDescripción
reasonstring✅customerRequest, bankError, fraud, cashierError
amountnumber❌Centavos, entero > 0. Si se omite, se devuelve todo lo que queda por reversar
descriptionstring❌Hasta 140 caracteres
referencestring❌Tu referencia interna del reverso; vuelve en el webhook como reference
{
"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).

HTTPcodeCuándo
400—reason inválido o amount no es entero positivo
400IDEMPOTENCY_KEY_REQUIREDFalta X-Idempotency-Key
402INSUFFICIENT_BALANCETu saldo disponible no cubre el monto (availableBalance, requiredAmount)
404—El cobro no existe o no es tuyo
409NOT_REVERSIBLEEl cobro no está COMPLETED, no tiene e2eId o es él mismo un reverso
409ALREADY_FULLY_REVERSEDYa se devolvió todo el cobro
422REVERSAL_EXCEEDS_REMAININGamount supera lo que queda (remainingAmount)
422PROVIDER_REJECTEDLa 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

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.

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.