余额变动

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

本页的事件

事件	通知什么	类型
`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 对象。外层结构所有事件都一样，参见事件结构。

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

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

{
  "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
}

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

{
  "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 或 Get developer balances。
核对手续费： 使用交易查询接口或 Generate reports。
避免手续费耗尽导致业务中断： 定期调用 List Fee Station token balance，并按自己的消耗速率设置告警。资金转出、退款和批量下发中的多个失败 code 都源于 Fee Station 余额不足。

概览

初始配置

收款

资金管理

索引信息

本页的事件

`payment.account.balance.updated`

事件内容

示例事件

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

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

保持自己账本的实时性

​本页的事件

​payment.account.balance.updated

​事件内容

​示例事件

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

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

​保持自己账本的实时性

本页的事件

`payment.account.balance.updated`

事件内容

示例事件

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

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

保持自己账本的实时性