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,
  "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。

使用场景

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 Avista
    participant YourSystem

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