CashOutReversal

概述

CashOutReversal 事件在您收到之前发送的 PIX 的退回时发送。这可能发生在以下情况：

收款方自愿退还金额
原始交易存在问题（数据无效、账户已关闭等）
目标银行拒绝了交易

CashOutReversal 的 movementType 为 CREDIT，因为您正在收回之前离开您账户的资金。

字段	值
`event`	`CashOutReversal`
`movementType`	`CREDIT`
含义	您收回了之前发送的资金

完整负载

{
  "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 特有字段

CashOutReversal 在 metadata 中包含附加字段以及 parentTransaction 对象。

metadata.refund

metadata.refundobject

收到的退回详情。

metadata.refund.valuenumber

退回金额（以分为单位）。

示例： 8（R$ 0.08）

metadata.refund.originalValuenumber

原始交易金额（以分为单位）。

示例： 31000（R$ 310.00）

metadata.refund.referenceTransactionIdnumber

提供商处的内部参考交易 ID。

parentTransaction

parentTransactionobjectobrigatorio

被退回的原始 PIX Out 交易数据。

parentTransaction.transactionIdstring

原始 PIX Out 交易的数字 ID（以字符串形式返回）。

parentTransaction.externalIdstring

您在创建 PIX Out 时提供的外部 ID。

parentTransaction.wasTotalRefundedboolean

指示总金额是否已全部退回。

true：全额退回
false：部分退回

parentTransaction.remainingAmountForRefundnumber

仍可退回的剩余金额（BRL）。

parentTransaction.counterpartobject

退回 PIX 的原始收款方数据。

区别：CashInReversal vs CashOutReversal

方面	CashInReversal	CashOutReversal
发起方	您（通过 Refund-In API）	收款方或目标银行
方向	您 -> 原始付款方	收款方 -> 您
movementType	`DEBIT`（出账）	`CREDIT`（入账）
发生时机	您决定退还	您收到退回的资金

使用场景

1. 收到退回

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. 拒绝处理

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

典型流程

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