CashOutReversal

Descripción General

El evento CashOutReversal se envía cuando usted recibe una reversión de un PIX que envió previamente. Esto puede ocurrir cuando:

El destinatario devuelve voluntariamente el monto
Hay un problema con la transacción original (datos inválidos, cuenta cerrada, etc.)
El banco de destino rechaza la transacción

El movementType para CashOutReversal es CREDIT, porque está recibiendo de vuelta dinero que había salido de su cuenta.

Campo	Valor
`event`	`CashOutReversal`
`movementType`	`CREDIT`
Significado	Recibió de vuelta dinero que había enviado

Payload Completo

{
  "event": "CashOutReversal",
  "status": "CONFIRMED",
  "transactionType": "PIX",
  "movementType": "CREDIT",
  "transactionId": "22222",
  "externalId": null,
  "endToEndId": "D18236120202512112009s0018351d9f",
  "pixKey": "07646173380",
  "feeAmount": 0.01,
  "originalAmount": 0.08,
  "finalAmount": 0.07,
  "processingDate": "2025-12-11T20:09:27.786Z",
  "errorCode": null,
  "errorMessage": null,
  "metadata": {
    "refund": {
      "value": 8,
      "originalValue": 31000,
      "referenceTransactionId": 917561
    },
    "provider": "hyperwallet",
    "counterpart": {
      "bankCode": "260",
      "bankIspb": "18236120",
      "bankName": "NU PAGAMENTOS S.A. - INSTITUIÇÃO DE PAGAMENTO"
    },
    "webhookEvent": "PixOutReversalExternal",
    "originatedFrom": "WEBHOOK_DIRECT"
  },
  "parentTransaction": {
    "transactionId": "67890",
    "externalId": "PIX-OUT-5483571657-OWUJDUDVDO",
    "endToEndId": "E071368472025121120065P1T3N1CS1A",
    "processingDate": "2025-12-11T20:06:12.117Z",
    "wasTotalRefunded": false,
    "remainingAmountForRefund": 0.22,
    "metadata": {},
    "counterpart": {
      "name": "Ana Costa",
      "document": "*.765.432-**",
      "bank": {
        "bankISPB": null,
        "bankName": null,
        "bankCode": "260",
        "accountBranch": null,
        "accountNumber": null
      }
    }
  }
}

Campos Específicos de CashOutReversal

CashOutReversal incluye campos adicionales en metadata y el objeto parentTransaction.

metadata.refund

metadata.refundobject

Detalles de la reversión recibida.

metadata.refund.valuenumber

Monto revertido en centavos.

Ejemplo: 8 (R$ 0.08)

metadata.refund.originalValuenumber

Monto original de la transacción en centavos.

Ejemplo: 31000 (R$ 310.00)

metadata.refund.referenceTransactionIdnumber

ID de transacción de referencia interna en el proveedor.

parentTransaction

parentTransactionobjectobrigatorio

Datos de la transacción PIX Out original que fue revertida.

parentTransaction.transactionIdstring

ID numérico de la transacción PIX Out original (retornado como string).

parentTransaction.externalIdstring

ID externo que proporcionó al crear el PIX Out.

parentTransaction.wasTotalRefundedboolean

Indica si el monto total fue revertido.

true: Reversión total
false: Reversión parcial

parentTransaction.remainingAmountForRefundnumber

Monto restante que aún puede revertirse (en BRL).

parentTransaction.counterpartobject

Datos del destinatario original que revirtió el PIX.

Diferencia: CashInReversal vs CashOutReversal

Aspecto	CashInReversal	CashOutReversal
Quién inicia	Usted (vía API de Refund-In)	El destinatario o el banco de destino
Dirección	Usted -> Pagador original	Destinatario -> Usted
movementType	`DEBIT` (salida)	`CREDIT` (entrada)
Cuándo ocurre	Usted decide retornar	Usted recibe dinero de vuelta

Casos de Uso

1. Reversión Recibida

async function handleCashOutReversal(payload) {
  const { parentTransaction, metadata } = payload;

  // Credit the reversed amount to the balance
  await balanceService.credit({
    amount: payload.finalAmount,
    reference: payload.transactionId,
    originalPaymentId: parentTransaction.transactionId
  });

  // Update original payment status
  await paymentService.markAsRefunded({
    paymentId: parentTransaction.externalId,
    refundAmount: payload.originalAmount,
    wasFullRefund: parentTransaction.wasTotalRefunded
  });

  // Notify finance team
  await notificationService.sendRefundReceived({
    originalAmount: metadata.refund.originalValue / 100,
    refundAmount: metadata.refund.value / 100
  });
}

2. Manejo de Rechazo

async function handleCashOutReversal(payload) {
  // If the PIX was returned, it may be a bank rejection
  if (payload.metadata.originatedFrom === 'WEBHOOK_DIRECT') {
    console.log('PIX rejected by destination bank');

    await transferService.markAsFailed({
      transferId: payload.parentTransaction.externalId,
      reason: 'Returned by destination bank'
    });

    // Notify user to verify data
    await notificationService.sendTransferFailed();
  }
}

Flujo Típico

sequenceDiagram
    participant YourSystem
    participant Avista
    participant Recipient

    Note over YourSystem,Recipient: Original transaction (CashOut)
    YourSystem->>Avista: POST /api/pix/payment
    Avista->>Recipient: PIX sent
    Avista->>YourSystem: Webhook CashOut

    Note over YourSystem,Recipient: Reversal (CashOutReversal)
    Recipient->>Avista: Returns PIX
    Avista->>Avista: Processes reversal
    Avista->>YourSystem: Webhook CashOutReversal
    YourSystem-->>Avista: HTTP 200 OK
    YourSystem->>YourSystem: Credits balance