Account 对接指南

Account API 用于确认商户账户身份、读取余额、查看入金/提现记录，以及通过账务流水完成对账。

使用场景

验证 API Key 是否属于正确账户
查询当前可用余额
排查入金和提现记录
通过 ledger 做财务对账

账户验证

接口

GET /payment/account

该接口用于确认当前 Bearer Token 对应的账户。

建议检查：

merchant_id
account_id
status
currencies
账户是否属于预期商户

账户列表

接口

GET /payment/accounts

适用于一个商户下有多个账户的情况。

常见查询参数：

参数	说明
`status`	按账户状态过滤
`limit`	分页条数
`offset`	分页偏移量

余额查询

接口

GET /payment/balances

可选按币种过滤：

GET /payment/balances?currency=USD

余额是时间点数据，不应替代 ledger 对账。出金前可以查询余额作为操作前校验，但最终财务仍建议以 ledger 为准。

入金查询

接口

GET /payment/deposits

常见过滤参数：

参数	说明
`currency`	币种
`network`	网络或通道
`status`	入金状态
`start_at` / `end_at`	查询时间范围
`limit` / `offset`	分页

提现查询

接口

GET /payment/withdrawals

用于排查商户账户资金转出记录。

Ledger 对账

接口

GET /payment/ledger

Ledger 是推荐的对账主数据源。

对账建议：

按时间窗口拉取 ledger
用 currency 分币种核对
保存平台交易 ID 和商户业务 ID
对余额快照和 ledger 明细做交叉校验
对异常差异保留 API 响应日志

最佳实践

生产系统启动时先验证账号
余额展示要标明数据时间
出金前可以查询余额，但不要只依赖余额做最终对账
财务结算和审计应以 ledger 为准
所有查询接口都应支持分页和重试

使用场景​

推荐接入顺序​

账户验证​

账户列表​

余额查询​

入金查询​

提现查询​

Ledger 对账​

最佳实践​