CashOutReversal

Overview

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

The recipient voluntarily returns the amount
There is an issue 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 that 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,
  "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
      }
    }
  }
}

CashOutReversal-Specific Fields

CashOutReversal includes additional fields in metadata and the parentTransaction object.

metadata.refund

metadata.refundobject

Details of the received reversal.

metadata.refund.valuenumber

Reversed amount in cents.

Example: 8 (R$ 0.08)

metadata.refund.originalValuenumber

Original transaction amount in cents.

Example: 31000 (R$ 310.00)

metadata.refund.referenceTransactionIdnumber

Internal reference transaction ID at the provider.

parentTransaction

parentTransactionobjectobrigatorio

Data about the original PIX Out transaction that was reversed.

parentTransaction.transactionIdstring

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

parentTransaction.externalIdstring

External ID you provided when creating the PIX Out.

parentTransaction.wasTotalRefundedboolean

Indicates whether the total amount was reversed.

true: Full reversal
false: Partial reversal

parentTransaction.remainingAmountForRefundnumber

Remaining amount that can still be reversed (in BRL).

parentTransaction.counterpartobject

Data about the original recipient who reversed the PIX.

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` (outflow)	`CREDIT` (inflow)
When it occurs	You decide to return	You receive money back

Use Cases

1. Reversal Received

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. Rejection Handling

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();
  }
}

Typical Flow

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