> ## Documentation Index
> Fetch the complete documentation index at: https://cobo.com/payments/llms.txt
> Use this file to discover all available pages before exploring further.

# 余额变动

余额变动汇报任意链路背后的账目变化，无论由哪笔支付业务引起。请先阅读[事件概述](/payments/cn/guides/events/overview)了解外层结构、去重方式以及所有事件通用的规则。

## 本页的事件

| 事件 | 通知什么 | 类型 |
| - | - | - |
| [`payment.account.balance.updated`](#payment-account-balance-updated) | 某个账户在某个 token 上的可用余额发生变动，以及变动来源。各账户实际收到的金额只由此事件提供。 | **标准事件** |

## `payment.account.balance.updated`

某个 Payments 账户在某个 token 上的可用余额发生变化时触发。

它也是您了解**每个账户实际收到多少**的途径。例如订单的 `credited_amount` 包含将要分给您的开发者手续费，因此它不是商户的入账金额。一笔订单结算会为涉及的每个账户各产生一条余额事件。

### 事件内容

| 字段 | 类型 | 说明 |
| - | - | - |
| `data_type` | `string` | 固定为 `PaymentAccountBalanceUpdate`。 |
| `source_account` | `string` | 发生变动的账户。商户账户为商户 ID，开发者账户为 `developer`。 |
| `source_id` | `string` | 引起本次变动的业务单据 ID：订单 ID、退款 ID、转出 ID、批量下发条目 ID，充值和意外入金为交易 ID。 |
| `source_type` | `string` | 变动来源： • `OrderIn`：订单收款（含订单终态后的晚付金额）。 • `TopUp`：充值。 • `UnexceptedIn`：意外入金。 • `RefundOut`：退款。 • `Payout`：转出。 • `UnexceptedOut`：意外出金。 • `Allocation`：资金分配。 • `BulkSend`：批量下发。 • `SettlementNetwork`：结算网络。 • `OnrampIn`：法币入金（On-Ramp）。 |
| `token_id` | `string` | 发生变动的 token。 |
| `amount` | `string` | 变动金额，截断至两位小数。 |
| `amount_raw` | `string` | 同一笔变动金额，按该 token 自身的精度表示，不补尾零（例如 `100`、`0.123456`）。 |
| `balance_before` | `string` | 变动前余额，截断至两位小数。 |
| `balance_before_raw` | `string` | 变动前余额，按该 token 自身的精度表示。 |
| `balance_after` | `string` | 变动后余额，截断至两位小数。 |
| `balance_after_raw` | `string` | 变动后余额，按该 token 自身的精度表示。 |
| `flow_direction` | `string` | 变动方向： • `in`：资金流入该账户。 • `out`：资金流出该账户。 |
| `update_time` | `integer` | 余额更新时间，Unix 时间戳（秒）。 |

### 示例事件

以下示例只展示 `data` 对象。外层结构所有事件都一样，参见[事件结构](/payments/cn/guides/events/overview#事件结构)。

#### 一笔订单同时给商户和开发者入账

一笔订单结算会为每个账户各产生一条事件。两条相加等于订单的 `credited_amount`。

```json theme={null}
{
  "data_type": "PaymentAccountBalanceUpdate",
  "source_account": "M1001",
  "source_id": "order_001",
  "source_type": "OrderIn",
  "token_id": "ETH_USDC",
  "amount": "100.00",
  "amount_raw": "100",
  "balance_before": "1250.00",
  "balance_before_raw": "1250",
  "balance_after": "1350.00",
  "balance_after_raw": "1350",
  "flow_direction": "in",
  "update_time": 1744690100
}
```

```json theme={null}
{
  "data_type": "PaymentAccountBalanceUpdate",
  "source_account": "developer",
  "source_id": "order_001",
  "source_type": "OrderIn",
  "token_id": "ETH_USDC",
  "amount": "2.00",
  "amount_raw": "2",
  "balance_before": "830.00",
  "balance_before_raw": "830",
  "balance_after": "832.00",
  "balance_after_raw": "832",
  "flow_direction": "in",
  "update_time": 1744690100
}
```

#### 一笔转出从开发者账户扣出

`flow_direction` 为 `out`，`source_id` 是 payout ID。

```json theme={null}
{
  "data_type": "PaymentAccountBalanceUpdate",
  "source_account": "developer",
  "source_id": "payout_001",
  "source_type": "Payout",
  "token_id": "ETH_USDC",
  "amount": "500.00",
  "amount_raw": "500",
  "balance_before": "832.00",
  "balance_before_raw": "832",
  "balance_after": "332.00",
  "balance_after_raw": "332",
  "flow_direction": "out",
  "update_time": 1744700600
}
```

## 保持自己账本的实时性

Webhook 消息不携带实时余额，以保证您读到的数值不会因为并发活动而失真。

* **随事件更新余额：** 收到 Webhook 时调用 [List merchant balances](/payments/en/api-references/payment/list-merchant-balances) 或 [Get developer balances](/payments/en/api-references/payment/get-developer-balance)。
* **核对手续费：** 使用交易查询接口或 [Generate reports](/payments/en/api-references/payment/generate-reports)。
* **避免手续费耗尽导致业务中断：** 定期调用 [List Fee Station token balance](https://www.cobo.com/developers/v2/api-references/feestation/list-fee-station-token-balances)，并按自己的消耗速率设置告警。资金转出、退款和批量下发中的多个失败 code 都源于 Fee Station 余额不足。