CashOutReversal

Overview

The CashOutReversal event is sent when you receive a refund of a PIX you sent previously. This can occur when:

The recipient voluntarily returns the amount
There is a problem with the original transaction (invalid data, closed account, etc.)
The destination bank rejects the transaction

The movementType for CashOutReversal is CREDIT, because you are receiving back money that had left your account.

Field	Value
`event`	`CashOutReversal`
`movementType`	`CREDIT`
Meaning	You received back money you had sent

Full Payload

{
  "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
      }
    }
  }
}

CashOutReversal-Specific Fields

CashOutReversal includes the parentTransaction object with the data of the original PIX Out.

In this event, the metadata is filled in by the platform with information about the refund received from the PSP. The content varies by PSP and is for reference only: do not depend on specific keys in it. For amounts, use originalAmount, feeAmount and finalAmount.

parentTransaction

parentTransactionobjectobrigatorio

Data about the original PIX Out transaction that was refunded.

parentTransaction.transactionIdstring

Numeric ID of the original PIX Out transaction (returned as a string).

parentTransaction.externalIdstring | null

External ID you provided when creating the PIX Out.

parentTransaction.endToEndIdstring | null

End-to-End ID of the original PIX Out.

parentTransaction.processingDatestring

Creation date of the original PIX Out (ISO 8601 UTC).

parentTransaction.wasTotalRefundedboolean

Indicates whether the full amount was refunded.

true: Full refund
false: Partial refund

parentTransaction.remainingAmountForRefundnumber

Remaining amount that can still be refunded (in reais).

parentTransaction.providerIdstring | null

Identifier of the original PIX Out at the PSP. null if absent.

parentTransaction.metadataobject

metadata of the original PIX Out.

parentTransaction.counterpartobject

Data about the original recipient who returned the PIX (same structure as the CashOut counterpart).

Difference: CashInReversal vs CashOutReversal

Aspect	CashInReversal	CashOutReversal
Who initiates	You (via Refund-In API)	The recipient or the destination bank
Direction	You → Original payer	Recipient → You
movementType	`DEBIT` (outgoing)	`CREDIT` (incoming)
When it occurs	You decide to return	You receive back

Use Cases

1. Refund Received

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

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

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

  // Notify finance team
  await notificationService.sendRefundReceived({
    paymentId: parentTransaction.externalId,
    refundAmount: payload.originalAmount
  });
}

Typical Flow

sequenceDiagram
    participant YourSystem
    participant FyPay
    participant Recipient

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

    Note over YourSystem,Recipient: Refund (CashOutReversal)
    Recipient->>FyPay: Returns PIX
    FyPay->>FyPay: Processes refund
    FyPay->>YourSystem: CashOutReversal Webhook
    YourSystem-->>FyPay: HTTP 2xx
    YourSystem->>YourSystem: Credits balance

CashOutReversal

Overview

Full Payload

CashOutReversal-Specific Fields

parentTransaction

Difference: CashInReversal vs CashOutReversal

Use Cases

1. Refund Received

Typical Flow

Next Steps

PIX Cash-Out

CashOut

On this page