CashInReversal

Overview

The CashInReversal event is sent when you initiate a refund of a previously received PIX payment, returning the amount to the original payer. This event occurs when you call the Refund-In API.

The movementType for CashInReversal is DEBIT, because you are returning money that had entered your account.

Field	Value
`event`	`CashInReversal`
`movementType`	`DEBIT`
Meaning	You returned money that you had received

Full Payload

{
  "event": "CashInReversal",
  "status": "CONFIRMED",
  "transactionType": "PIX",
  "movementType": "DEBIT",
  "transactionId": "11111",
  "externalId": "refund-678689ca-3e16-4f5e-a08f-09a984a97781",
  "endToEndId": "D07136847202512112011O5222ZRBI5A",
  "pixKey": null,
  "feeAmount": 0.01,
  "originalAmount": 0.3,
  "finalAmount": 0.31,
  "processingDate": "2025-12-11T20:11:13.289Z",
  "errorCode": null,
  "errorMessage": null,
  "metadata": {},
  "parentTransaction": {
    "transactionId": "12345",
    "externalId": "PIX-5482123298-EJUYFSMU1UU",
    "endToEndId": "E00416968202512111942rjzxxzSSTD9",
    "processingDate": "2025-12-11T19:42:04.080Z",
    "wasTotalRefunded": false,
    "remainingAmountForRefund": 0.2,
    "metadata": {},
    "counterpart": {
      "name": "Carlos Oliveira",
      "document": "*.345.678-**",
      "bank": {
        "bankISPB": null,
        "bankName": null,
        "bankCode": null,
        "accountBranch": null,
        "accountNumber": null
      }
    }
  }
}

CashInReversal-Specific Fields

CashInReversal includes the parentTransaction object with data about the original transaction being refunded.

parentTransaction

parentTransactionobjectobrigatorio

Data about the original PIX In transaction being refunded.

parentTransaction.transactionIdstring

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

parentTransaction.externalIdstring

External ID of the original transaction.

parentTransaction.endToEndIdstring

End-to-End ID of the original transaction.

parentTransaction.processingDatestring

Processing date of the original transaction.

parentTransaction.wasTotalRefundedboolean

Indicates whether the total amount of the original transaction was refunded.

true: Full refund (no further refunds possible)
false: Partial refund (remaining amount can still be refunded)

parentTransaction.remainingAmountForRefundnumber

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

Example: 0.2 (R$ 0.20 can still be refunded)

parentTransaction.counterpartobject

Data about the original payer who will receive the refund.

Full Refund vs Partial Refund

Full Refund

When you return 100% of the received amount:

{
  "parentTransaction": {
    "wasTotalRefunded": true,
    "remainingAmountForRefund": 0
  }
}

Partial Refund

When you return only part of the amount:

{
  "parentTransaction": {
    "wasTotalRefunded": false,
    "remainingAmountForRefund": 0.2
  }
}

You can make multiple partial refunds until wasTotalRefunded is true.

Use Cases

1. Duplicate Payment Refund

async function handleCashInReversal(payload) {
  const refundId = payload.transactionId;
  const originalOrderId = payload.parentTransaction.externalId;

  await refundService.markAsCompleted({
    refundId,
    originalOrderId,
    amount: payload.originalAmount,
    completedAt: payload.processingDate
  });

  // Notify customer about the refund
  await notificationService.sendRefundConfirmation({
    orderId: originalOrderId,
    amount: payload.originalAmount
  });
}

2. Partial Refund Tracking

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

  await refundService.updateStatus({
    originalTransactionId: parentTransaction.transactionId,
    totalRefunded: !parentTransaction.wasTotalRefunded
      ? false
      : true,
    remainingAmount: parentTransaction.remainingAmountForRefund
  });

  if (parentTransaction.wasTotalRefunded) {
    console.log('Transaction fully refunded');
  } else {
    console.log(`Still available for refund: R$ ${parentTransaction.remainingAmountForRefund}`);
  }
}

Typical Flow

sequenceDiagram
    participant YourSystem
    participant Avista
    participant OriginalPayer

    Note over YourSystem,OriginalPayer: Original transaction (CashIn)
    OriginalPayer->>Avista: PIX received previously
    Avista->>YourSystem: Webhook CashIn

    Note over YourSystem,OriginalPayer: Refund (CashInReversal)
    YourSystem->>Avista: POST /api/pix/refund-in/\{id\}
    Avista->>OriginalPayer: Returns PIX
    Avista->>YourSystem: Webhook CashInReversal
    YourSystem-->>Avista: HTTP 200 OK