CashInReversal

概述

当之前收到的 PIX 被退款、金额退还给原始付款方时，会发送 CashInReversal 事件。通常在您调用 Refund-In API（POST /api/pix/refund-in/:id）时发生，但也可能在 PSP 发起退还时发生，例如 MED 的退还。

CashInReversal 的 movementType 为 DEBIT，因为您正在退还之前进入您账户的资金。

字段	值
`event`	`CashInReversal`
`movementType`	`DEBIT`
含义	您退还了之前收到的资金

完整负载

{
  "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,
  "mismatchAmount": null,
  "processingDate": "2025-12-11T20:11:13.289Z",
  "errorCode": null,
  "errorMessage": null,
  "providerId": "r1e2f3u4n5",
  "metadata": {},
  "parentTransaction": {
    "transactionId": "12345",
    "externalId": "PIX-5482123298-EJUYFSMU1UU",
    "endToEndId": "E00416968202512111942rjzxxzSSTD9",
    "processingDate": "2025-12-11T19:42:04.080Z",
    "wasTotalRefunded": false,
    "remainingAmountForRefund": 0.2,
    "providerId": "a1b2c3d4e5",
    "metadata": {},
    "counterpart": {
      "name": "Carlos Oliveira",
      "document": "*.345.678-**",
      "bank": {
        "bankISPB": null,
        "bankName": null,
        "bankCode": null,
        "accountBranch": null,
        "accountNumber": null
      }
    }
  }
}

CashInReversal 特有字段

CashInReversal 包含 parentTransaction 对象，其中包含正在退款的原始交易数据。

parentTransaction

parentTransactionobjectobrigatorio

正在退款的原始 PIX In 交易数据。

parentTransaction.transactionIdstring

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

parentTransaction.externalIdstring | null

原始交易的外部 ID。

parentTransaction.endToEndIdstring | null

原始交易的 End-to-End ID。

parentTransaction.processingDatestring

原始交易的创建日期（ISO 8601 UTC）。

parentTransaction.wasTotalRefundedboolean

指示原始交易的总金额是否已全部退款。

true：全额退款（无法再进行退款）
false：部分退款（剩余金额仍可退款）

parentTransaction.remainingAmountForRefundnumber

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

示例： 0.2（还可退 R$ 0.20）

parentTransaction.providerIdstring | null

原始交易在 PSP 中的标识符。缺失时为 null。

parentTransaction.metadataobject

原始交易的 metadata。

parentTransaction.counterpartobject

将收到退款的原始付款方数据（结构与 CashIn 的 counterpart 相同）。

全额退款 vs 部分退款

全额退款

当您退还收到的全部金额时：

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

部分退款

当您仅退还部分金额时：

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

您可以进行多次部分退款，直到 wasTotalRefunded 为 true。

使用场景

1. 重复付款退款

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. 部分退款追踪

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

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

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

典型流程

sequenceDiagram
    participant YourSystem
    participant FyPay
    participant OriginalPayer

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

    Note over YourSystem,OriginalPayer: Refund (CashInReversal)
    YourSystem->>FyPay: POST /api/pix/refund-in/:id
    FyPay->>OriginalPayer: Returns PIX
    FyPay->>YourSystem: Webhook CashInReversal
    YourSystem-->>FyPay: HTTP 2xx