CashOut
概述
当从您的账户发出的 PIX 付款达到最终状态时，会发送 CashOut 事件：CONFIRMED（转账完成）或 ERROR（转账未完成）。
此事件对 PIX 密钥付款（/api/pix/cash-out）和二维码付款（/api/pix/cash-out-qrcode）都会触发。
CashOut 的 movementType 始终为 DEBIT，表示资金从账户流出。
| 字段 | 值 |
|---|---|
event | CashOut |
movementType | DEBIT |
| 含义 | 资金离开您的账户 |
完整负载
{
"event": "CashOut",
"status": "CONFIRMED",
"transactionType": "PIX",
"movementType": "DEBIT",
"transactionId": "67890",
"externalId": "PIX-OUT-5483571657-OWUJDUDVDO",
"endToEndId": "E071368472025121120065P1T3N1CS1A",
"pixKey": "07646173380",
"feeAmount": 0.01,
"originalAmount": 0.30,
"finalAmount": 0.31,
"mismatchAmount": null,
"processingDate": "2025-12-11T20:06:12.117Z",
"errorCode": null,
"errorMessage": null,
"providerId": "f6e5d4c3b2",
"counterpart": {
"name": "Ana Costa",
"document": "*.765.432-**",
"bank": {
"bankISPB": null,
"bankName": null,
"bankCode": "260",
"accountBranch": null,
"accountNumber": null
}
},
"metadata": {}
}CashOut 特有字段
CashOut 包含 counterpart 对象，其中包含收款方（接收 PIX 的人）的数据。
counterpartobjectobrigatorio收款方（接收您发送的 PIX 的人）的数据。
counterpart.namestring | null收款方在目标银行注册的全名。
counterpart.documentstring | null收款方的 CPF/CNPJ，格式以 PSP 提供的为准（可能部分脱敏）。
示例： "*.765.432-**"
counterpart.bankobject收款方的银行信息：bankISPB、bankName、bankCode、accountBranch 和 accountNumber。该对象始终包含这五个键；数据不可用时对应值为 null。
counterpart.bank.bankCodestring | null收款方银行的 COMPE 代码。
示例： "260"（Nubank）
counterpart.bank.bankISPBstring | null收款方银行的 ISPB 代码。
counterpart.bank.bankNamestring | null收款方银行名称。
最终金额计算
对于 DEBIT 事件（出账），最终金额计算如下：
finalAmount = originalAmount + feeAmount手续费（feeAmount）会加到原始金额上。如果您发送了 R$ 100.00，手续费为 R$ 0.50，那么从您账户的总扣款为 R$ 100.50。
使用场景
1. 供应商付款
async function handleCashOut(payload) {
const paymentId = payload.externalId.replace('PIX-OUT-', '');
await paymentService.markAsCompleted({
paymentId,
transactionId: payload.transactionId,
endToEndId: payload.endToEndId,
completedAt: payload.processingDate
});
// Notify finance team
await notificationService.sendPaymentCompleted(paymentId);
}2. 客户提现
async function handleCashOut(payload) {
await withdrawalService.confirm({
withdrawalId: payload.externalId,
transactionId: payload.transactionId,
amount: payload.originalAmount,
fee: payload.feeAmount
});
}典型流程
sequenceDiagram
participant YourSystem
participant FyPay
participant Recipient
YourSystem->>FyPay: POST /api/pix/cash-out
FyPay->>FyPay: Validates and processes
FyPay->>Recipient: Transfers PIX
Recipient-->>FyPay: Confirmation
FyPay->>YourSystem: Webhook CashOut
YourSystem-->>FyPay: HTTP 2xx错误处理
当 CashOut 失败时，您将收到 status: "ERROR" 的 webhook，并且 errorCode/errorMessage 字段会被填充：
{
"event": "CashOut",
"status": "ERROR",
"transactionType": "PIX",
"movementType": "DEBIT",
"transactionId": "67890",
"externalId": "PIX-OUT-5483571657-OWUJDUDVDO",
"endToEndId": null,
"pixKey": "07646173380",
"feeAmount": 0.01,
"originalAmount": 0.30,
"finalAmount": 0.31,
"mismatchAmount": null,
"processingDate": "2025-12-11T20:06:12.117Z",
"errorCode": "TAX_ID_MISMATCH",
"errorMessage": "O documento informado não corresponde ao titular da chave PIX",
"providerId": null,
"counterpart": {
"name": "Ana Costa",
"document": "12345678900",
"bank": {
"bankISPB": null,
"bankName": null,
"bankCode": null,
"accountBranch": null,
"accountNumber": null
}
},
"metadata": {}
}当 status 为 ERROR 时，endToEndId 通常为 null，因为 PIX 未完成清算。feeAmount 和 finalAmount 显示为该操作计算的金额，但不会从您的账户扣除任何款项。
当 status 为 ERROR 时，金额不会从您的账户扣除。请处理错误并通知用户。
错误代码因清算机构而异。 errorCode 的值取决于您账户的清算机构。请将 errorCode 字段作为通用字符串处理，不要用于业务逻辑；向用户展示 errorMessage。