CashOut

概述

CashOut 事件在 PIX 付款成功从您的账户发送到另一个账户时发送。它表示转账已完成。

此事件对 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,
  "processingDate": "2025-12-11T20:06:12.117Z",
  "errorCode": null,
  "errorMessage": null,
  "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

收款方在目标银行注册的全名。

counterpart.documentstring

收款方的 CPF/CNPJ（部分脱敏以保护隐私）。

示例： "*.765.432-**"

counterpart.bankobject

收款方的银行信息。

counterpart.bank.bankCodestring

收款方银行的 COMPE 代码。

示例： "260"（Nubank）

最终金额计算

对于 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 Avista
    participant Recipient

    YourSystem->>Avista: POST /api/pix/payment
    Avista->>Avista: Validates and processes
    Avista->>Recipient: Transfers PIX
    Recipient-->>Avista: Confirmation
    Avista->>YourSystem: Webhook CashOut
    YourSystem-->>Avista: HTTP 200 OK

错误处理

当 CashOut 失败时，您将收到 status: "ERROR" 的 webhook：

{
  "event": "CashOut",
  "status": "ERROR",
  "errorCode": "INVALID_PIX_KEY",
  "errorMessage": "Chave PIX não encontrada ou inválida",
  ...
}

当 status 为 ERROR 时，金额未从您的账户扣除。请处理错误并通知用户。

后续步骤

PIX Cash-Out

了解如何发送 PIX 付款

二维码 Cash-Out

通过 PIX 二维码付款

收到退回

了解退回事件

CashOut

PIX Cash-Out

二维码 Cash-Out

收到退回

本页目录