Reverso de Pay-Out

POST /v1/br/payout/pix/{txId}/reversal

Revierte un pay-out completado. Solo se pueden revertir transacciones en estado COMPLETED.

Parámetros de ruta

Parámetro	Descripción
txId	ID del pay-out a revertir

Request body

{ "reason": "customerRequest" }

Campo	Tipo	Requerido	Valores
reason	string	✅	customerRequest, bankError, fraud, cashierError

Response 201 Created

{
  "txId": "reversal-txid-xyz",
  "originalTxId": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7",
  "status": "PROCESSING",
  "amount": 5000,
  "feeCharged": 200,
  "totalDebit": 5200,
  "currency": "BRL"
}

Campo	Descripción
txId	ID de la transacción de reverso
originalTxId	ID del pay-out original que se está revirtiendo
status	Estado inicial (PROCESSING)
amount	Monto revertido en centavos
feeCharged	Fee cobrado por el reverso en centavos
totalDebit	Total debitado de tu balance (amount + feeCharged)

Nota

El totalDebit se reserva en tu balance al crear el reverso. Se confirma cuando el proveedor envía la confirmación.

Errores

Código	Causa
404	Pay-out no encontrado o no pertenece al cliente
409	La transacción no está en estado COMPLETED, o no tiene endToEndId
402	Saldo insuficiente para cubrir amount + fee
502	Error del proveedor de pagos

Webhook de confirmación

Cuando el reverso se confirma, Rivopay envía el evento payout.reversed:

{
  "eventType": "payout.reversed",
  "txId": "reversal-txid-abc",
  "type": "PAYOUT",
  "status": "REVERSED",
  "amount": 5000,
  "currency": "BRL",
  "feeCharged": 200,
  "reason": "bankError",
  "e2eId": "E12345678202603241410000000001",
  "reversedAt": "2026-03-24T14:10:00.000Z",
  "debtor": { "..." : "..." },
  "creditor": { "..." : "..." },
  "metadata": {
    "reason": "bankError",
    "triggerTransactionId": "E12345678202603241402000000001"
  }
}