查询余额
契约 v1.0.0
listBalances/v1/balancesfinance:read 默认不在开发者可授予范围内，需要所有者或管理员创建的 Key。
按币种返回商户余额分桶，每个币种一条。结果一次返回、不分页：has_more 恒为 false，next_cursor 为 null。 绝不能把不同币种的金额相加为“总余额”；net_position 仅供展示，不能替代 available 判断可结算金额。
请求头
| 请求头 | 必填 | 格式 | 说明 |
|---|---|---|---|
| Authorization | 是 | Bearer <API_KEY> | 服务端密钥，只能在商户服务端使用；商户与环境由密钥推导。缺失、无效、撤销或过期返回 401。 |
查询参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
currency | string | 否 | 只返回指定币种。 约束： 示例： |
请求示例
curl -X GET 'https://api.payhub.bbpays.site/v1/balances?limit=20' \
-H 'Authorization: Bearer <TEST_SERVER_API_KEY>'需要替换的占位符
<TEST_SERVER_API_KEY>：测试环境服务端 API Key：在商户后台「API Key」页面创建
说明
服务端 API Key 只能在你的服务端使用，文档站不提供在线调试。获取测试 Key：商户后台 API Key（在新标签页打开商户后台）（测试环境；需要所有者、管理员或开发者）
响应
各币种余额。
{
"data": [
{
"currency": "USD",
"pending": 125000,
"available": 482050,
"reserve": 50000,
"risk_hold": 0,
"refund_pending": 3500,
"payout_pending": 200000,
"merchant_receivable": 0,
"book_payable": 860550,
"net_position": 860550
},
{
"currency": "JPY",
"pending": 300000,
"available": 1250000,
"reserve": 100000,
"risk_hold": 0,
"refund_pending": 0,
"payout_pending": 0,
"merchant_receivable": 0,
"book_payable": 1650000,
"net_position": 1650000
}
],
"has_more": false,
"next_cursor": null,
"request_id": "req_demo_030"
}响应字段
分页列表：data 为对象数组，has_more 为 true 时用 next_cursor 继续翻页。 字段说明见 对象小节。
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
data | array<Balance> | 必填 | |
currency | string | 必填 | 币种。 约束： 示例： |
pending | integer(int64) | 必填 | 待结算：支付已成功，但到账、账期或对账条件未全部满足的净额；不可打款。 约束： 示例： |
available | integer(int64) | 必填 | 可结算：已满足释放条件且未被占用的金额；唯一可用于打款的桶。 约束： 示例： |
reserve | integer(int64) | 必填 | 保证金：按规则留存、等待释放的金额。 约束： 示例： |
risk_hold | integer(int64) | 必填 | 风险冻结：与具体风险处置或争议关联的冻结金额。 约束： 示例： |
refund_pending | integer(int64) | 必填 | 退款占用：被审核中或处理中退款占用的金额。 约束： 示例： |
payout_pending | integer(int64) | 必填 | 打款占用：被有效结算单占用、尚未确认打款完成的金额。 约束： 示例： |
merchant_receivable | integer(int64) | 必填 | 待追偿：平台因真实强制扣收等形成的对商户应收债权；不属于商户可用资金。 约束： 示例： |
book_payable | integer(int64) | 必填 | 商户账面应付余额 = pending + available + reserve + risk_hold + refund_pending + payout_pending。 约束： 示例： |
net_position | integer(int64) | 必填 | 商户净头寸（仅展示用途）= book_payable - merchant_receivable，可为负；不能替代 available。 示例： |
has_more | boolean | 必填 | 恒为 false。 示例： |
next_cursor | string可为空 | 必填 | 恒为 null。 示例： |
request_id | string | 必填 | 本次请求的唯一标识。 示例： |
可能的错误码
| HTTP | 错误码 | 何时出现 | 如何处理 |
|---|---|---|---|
| 400 | invalid_request | 缺 Idempotency-Key；订单号含非法字符；payment_method_data 与 payment_method_id 同时提交；confirm=false 携带卡信息；confirm=true 缺 return_url；收银会话两组身份参数同时提交或都缺；缺少上游要求的 browser_info / billing_details 字段；游标、时间格式、limit 不合法 | 按 error.field 修正后重新提交，不要自动重扣 |
| 401 | unauthenticated通用 | 未带 Authorization；Key 复制不完整；轮换后旧 Key 已过期；Key 被撤销 | 检查凭据，在 商户后台 API Key 页面 核对 Key 状态与环境 |
| 403 | forbidden通用 | 只读 Key 创建退款；getEvent 缺少事件所属业务的读权限；请求来源 IP 不在 Key 的白名单时返回更具体的 ip_not_allowed | 使用具备所需 scope 的 Key；不要绕过限制 |
| 429 | rate_limited通用 | 商户、Key 维度的频率限制；换 Key 不能绕过商户总限额 | 等待 Retry-After 秒后用原幂等键重试 |
| 500 | internal_error通用 | — | 用原幂等键重试或按商户订单号 / 退款号查询；不能换键重扣 |
| 502 / 503 | upstream_unavailable通用 | 上游或平台依赖故障，平台无法确认本次请求是否已生效 | 同上 |
注意事项
- 每个币种一条，一次返回、不分页（
has_more恒为 false）。 - 只有
available可用于打款；net_position仅供展示、可为负，不能替代available。
警告
不同币种的余额不能相加。