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

CashOutReversal 包含 parentTransaction 对象，其中包含原始 PIX Out 的数据。

在此事件中，metadata 由平台填充，包含从 PSP 收到的退回信息。其内容因 PSP 而异，仅供参考：请勿依赖其中的特定键。金额请使用 originalAmount、feeAmount 和 finalAmount。

parentTransaction

parentTransactionobjectobrigatorio

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

parentTransaction.transactionIdstring

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

parentTransaction.externalIdstring | null

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

parentTransaction.endToEndIdstring | null

原始 PIX Out 的 End-to-End ID。

parentTransaction.processingDatestring

原始 PIX Out 的创建日期（ISO 8601 UTC）。

parentTransaction.wasTotalRefundedboolean

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

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

parentTransaction.remainingAmountForRefundnumber

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

parentTransaction.providerIdstring | null

原始 PIX Out 在 PSP 中的标识符。缺失时为 null。

parentTransaction.metadataobject

原始 PIX Out 的 metadata。

parentTransaction.counterpartobject

退回 PIX 的原始收款方数据（结构与 CashOut 的 counterpart 相同）。

区别：CashInReversal vs CashOutReversal

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

使用场景

1. 收到退回

async function handleCashOutReversal(payload) {
  const { parentTransaction } = 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({
    paymentId: parentTransaction.externalId,
    refundAmount: payload.originalAmount
  });
}

典型流程

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: Webhook CashOut

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

CashOutReversal

概述

完整负载

CashOutReversal 特有字段

parentTransaction

区别：CashInReversal vs CashOutReversal

使用场景

1. 收到退回

典型流程

后续步骤

PIX Cash-Out

CashOut

本页目录