CashOutReversal

Descripción General

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

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

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

Campo	Valor
`event`	`CashOutReversal`
`movementType`	`CREDIT`
Significado	Usted 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,
  "mismatchAmount": null,
  "processingDate": "2025-12-11T20:09:27.786Z",
  "errorCode": null,
  "errorMessage": null,
  "providerId": "d3v0luc4o",
  "metadata": {
    "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,
    "providerId": "f6e5d4c3b2",
    "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 el objeto parentTransaction con los datos del PIX Out original.

En este evento, el metadata lo completa la plataforma con información de la devolución recibida del PSP. El contenido varía según el PSP y sirve solo como referencia: no dependa de claves específicas. Para los montos, use originalAmount, feeAmount y finalAmount.

parentTransaction

parentTransactionobjectobrigatorio

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

parentTransaction.transactionIdstring

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

parentTransaction.externalIdstring | null

ID externo que usted proporcionó al crear el PIX Out.

parentTransaction.endToEndIdstring | null

ID End-to-End del PIX Out original.

parentTransaction.processingDatestring

Fecha de creación del PIX Out original (ISO 8601 UTC).

parentTransaction.wasTotalRefundedboolean

Indica si el monto total fue devuelto.

true: Devolución total
false: Devolución parcial

parentTransaction.remainingAmountForRefundnumber

Monto restante que todavía puede devolverse (en reales).

parentTransaction.providerIdstring | null

Identificador del PIX Out original en el PSP. null si no existe.

parentTransaction.metadataobject

metadata del PIX Out original.

parentTransaction.counterpartobject

Datos del receptor original que devolvió el PIX (misma estructura que el counterpart de CashOut).

Diferencia: CashInReversal vs CashOutReversal

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

Casos de Uso

1. Devolución Recibida

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

  // Acreditar el monto devuelto en el saldo
  await balanceService.credit({
    amount: payload.finalAmount,
    reference: payload.transactionId,
    originalPaymentId: parentTransaction.transactionId
  });

  // Actualizar el estado del pago original
  await paymentService.markAsRefunded({
    paymentId: parentTransaction.externalId,
    refundAmount: payload.originalAmount,
    wasFullRefund: parentTransaction.wasTotalRefunded
  });

  // Notificar al equipo financiero
  await notificationService.sendRefundReceived({
    paymentId: parentTransaction.externalId,
    refundAmount: payload.originalAmount
  });
}

Flujo Típico

sequenceDiagram
    participant SuSistema
    participant FyPay
    participant Receptor

    Note over SuSistema,Receptor: Transacción original (CashOut)
    SuSistema->>FyPay: POST /api/pix/cash-out
    FyPay->>Receptor: PIX enviado
    FyPay->>SuSistema: Webhook CashOut

    Note over SuSistema,Receptor: Devolución (CashOutReversal)
    Receptor->>FyPay: Devuelve PIX
    FyPay->>FyPay: Procesa devolución
    FyPay->>SuSistema: Webhook CashOutReversal
    SuSistema-->>FyPay: HTTP 2xx
    SuSistema->>SuSistema: Acredita saldo

CashOutReversal

Descripción General

Payload Completo

Campos Específicos de CashOutReversal

parentTransaction

Diferencia: CashInReversal vs CashOutReversal

Casos de Uso

1. Devolución Recibida

Flujo Típico

Próximos Pasos

PIX Cash-Out

CashOut

En esta página