CashIn

概述

CashIn 事件在 PIX 付款成功到账到您的账户时发送。这是最常见的事件，表示资金已可用。

CashIn 的 movementType 始终为 CREDIT，表示资金流入账户。

字段	值
`event`	`CashIn`
`movementType`	`CREDIT`
含义	资金进入您的账户

完整负载

{
  "event": "CashIn",
  "status": "CONFIRMED",
  "transactionType": "PIX",
  "movementType": "CREDIT",
  "transactionId": "12345",
  "externalId": "PIX-5482123298-EJUYFSMU1UU",
  "endToEndId": "E00416968202512111942rjzxxzSSTD9",
  "pixKey": "1ff6ce09-4244-44d5-aa8f-1fe69f8986a9",
  "feeAmount": 0.01,
  "originalAmount": 0.5,
  "finalAmount": 0.49,
  "mismatchAmount": null,
  "processingDate": "2025-12-11T19:42:04.080Z",
  "errorCode": null,
  "errorMessage": null,
  "counterpart": {
    "name": "Carlos Oliveira",
    "document": "*.345.678-**",
    "bank": {
      "bankISPB": null,
      "bankName": null,
      "bankCode": null,
      "accountBranch": null,
      "accountNumber": null
    }
  },
  "metadata": {}
}

CashIn 特有字段

CashIn 包含 counterpart 对象，其中包含付款方（发送 PIX 的人）的数据。

counterpartobjectobrigatorio

付款方（向您发送 PIX 的人）的数据。

counterpart.namestring

付款方在发起银行注册的全名。

counterpart.documentstring

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

示例： "*.345.678-**"

counterpart.bankobject

付款方的银行信息。

counterpart.bank.bankISPBstring

付款方银行的 ISPB 代码（巴西支付系统中的唯一标识符）。

counterpart.bank.bankNamestring

付款方银行的名称。

counterpart.bank.bankCodestring

银行的 COMPE 代码（例如："001" 为 Banco do Brasil，"260" 为 Nubank）。

counterpart.bank.accountBranchstring

付款方的分行（如有）。

counterpart.bank.accountNumberstring

付款方的账号（如有）。

最终金额计算

对于 CREDIT 事件（入账），最终金额计算如下：

finalAmount = originalAmount - feeAmount

手续费（feeAmount）从原始金额中扣除。如果付款方发送了 R$ 100.00，手续费为 R$ 0.50，您将收到 R$ 99.50。

实际支付金额核对

originalAmount 字段为付款方实际支付的金额。在发货或提供服务之前，请始终将该值与您在收款码（QR Code）中生成的金额进行比较。

为便于核对，webhook 提供了 mismatchAmount 字段，已计算好差额：

`mismatchAmount`	含义
`null`	无差异——付款方支付的金额与应收金额完全一致。
正数	付款方支付的金额少于应收金额。例：`50.00` = 应收 R$ 100.00，实付 R$ 50.00。
负数	付款方支付的金额多于应收金额。例：`-50.00` = 应收 R$ 50.00，实付 R$ 100.00。

应收 R$ 100.00、实付 R$ 50.00 的示例：

{
  "type": "CashIn",
  "originalAmount": 50.0,
  "feeAmount": 0.5,
  "finalAmount": 49.5,
  "mismatchAmount": 50.0
}

在将订单视为已付款之前，请在对账中处理该差异。mismatchAmount 不为 null 表示收到的金额不是您所收取的金额。

使用场景

1. 订单付款

async function handleCashIn(payload) {
  // Use externalId to correlate with the order
  const orderId = payload.externalId.replace('PIX-', '');

  await orderService.markAsPaid({
    orderId,
    transactionId: payload.transactionId,
    amount: payload.finalAmount,
    paidAt: payload.processingDate
  });

  // Notify customer
  await notificationService.sendPaymentConfirmation(orderId);
}

2. 余额充值

async function handleCashIn(payload) {
  await walletService.credit({
    userId: payload.metadata.userId,
    amount: payload.finalAmount,
    reference: payload.transactionId
  });
}

典型流程

sequenceDiagram
    participant Payer
    participant Brasil Bitcoin
    participant YourSystem

    Payer->>Brasil Bitcoin: Sends PIX
    Brasil Bitcoin->>Brasil Bitcoin: Processes transaction
    Brasil Bitcoin->>YourSystem: Webhook CashIn
    YourSystem->>YourSystem: Validates authentication
    YourSystem->>YourSystem: Checks idempotency
    YourSystem-->>Brasil Bitcoin: HTTP 200 OK
    YourSystem->>YourSystem: Processes payment