查询账务流水
契约 v1.0.0
listBalanceTransactions/v1/balance-transactionsfinance:read 默认不在开发者可授予范围内，需要所有者或管理员创建的 Key。
查询脱敏的余额流水。每条流水是一个余额桶的增减：amount 为有符号整数，正数增加该桶，负数减少； 桶间转移表现为同一 ledger_transaction_id 下一减一增的两条流水。同时给出业务发生时间 occurred_at 与记账时间 booked_at。 以 booked_at 作为创建时间：按 booked_at 倒序、同一时间再按 id 倒序稳定排序，created_gte、created_lt 作用于 booked_at； 迟到的事实按实际记账时间出现，不改写历史流水。
请求头
| 请求头 | 必填 | 格式 | 说明 |
|---|---|---|---|
| Authorization | 是 | Bearer <API_KEY> | 服务端密钥，只能在商户服务端使用；商户与环境由密钥推导。缺失、无效、撤销或过期返回 401。 |
查询参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
currency | string | 否 | 按币种过滤。 约束： 示例： |
bucket | string | 否 | 按余额桶过滤。
示例： |
source_type | string | 否 | 按来源业务类型过滤，例如 payment、refund、dispute、settlement。 约束： 示例： |
source_id | string | 否 | 按来源业务对象 ID 过滤。 约束： 示例： |
limit | integer | 否 | 每页条数，默认 20，最大 100。 约束： |
cursor | string | 否 | 上一页响应中的 next_cursor。不透明字符串，客户端不得解析或拼接；须与首页使用相同的过滤条件。 约束： |
created_gte | string(date-time) | 否 | 创建时间下界（含），带时区的 ISO 8601。 示例： |
created_lt | string(date-time) | 否 | 创建时间上界（不含），带时区的 ISO 8601。 示例： |
请求示例
curl -X GET 'https://api.payhub.bbpays.site/v1/balance-transactions?limit=20' \
-H 'Authorization: Bearer <TEST_SERVER_API_KEY>'需要替换的占位符
<TEST_SERVER_API_KEY>：测试环境服务端 API Key：在商户后台「API Key」页面创建
说明
服务端 API Key 只能在你的服务端使用，文档站不提供在线调试。获取测试 Key：商户后台 API Key（在新标签页打开商户后台）（测试环境；需要所有者、管理员或开发者）
响应
账务流水列表。
{
"data": [
{
"id": "btx_demo_002",
"type": "funds_released",
"source_type": "payment",
"source_id": "pay_demo_001",
"bucket": "available",
"amount": 9650,
"currency": "USD",
"occurred_at": "2026-09-25T00:00:00Z",
"booked_at": "2026-09-25T00:00:02Z",
"ledger_transaction_id": "ltx_demo_001"
},
{
"id": "btx_demo_001",
"type": "funds_released",
"source_type": "payment",
"source_id": "pay_demo_001",
"bucket": "pending",
"amount": -9650,
"currency": "USD",
"occurred_at": "2026-09-25T00:00:00Z",
"booked_at": "2026-09-25T00:00:02Z",
"ledger_transaction_id": "ltx_demo_001"
}
],
"has_more": false,
"next_cursor": null,
"request_id": "req_demo_031"
}响应字段
分页列表：data 为对象数组，has_more 为 true 时用 next_cursor 继续翻页。 字段说明见 对象小节。
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
data | array<BalanceTransaction> | 必填 | |
id | string | 必填 | 流水号。 示例： |
type | string | 必填 | 记账类型，例如 payment_captured（支付成功入账）、refund_reserved（退款占用）、settlement_reserved（结算占用）、funds_released（资金释放）；须容忍新增取值。 示例： |
source_type | string | 必填 | 来源业务对象类型，例如 payment、refund、dispute、settlement、payout、payout_return（退汇）、adjustment。 示例： |
source_id | string | 必填 | 来源业务对象 ID。 示例： |
bucket | string | 必填 | 余额桶：pending、available、reserve、risk_hold、refund_pending、payout_pending、merchant_receivable。
示例： |
amount | integer(int64) | 必填 | 有符号金额，最小货币单位：正数增加该桶，负数减少该桶。 示例： |
currency | string | 必填 | 币种。 约束： 示例： |
occurred_at | string(date-time) | 必填 | 业务发生时间。 示例： |
booked_at | string(date-time) | 必填 | 记账时间；迟到事实不伪造为按时到达。 示例： |
ledger_transaction_id | string | 必填 | 关联的账务交易（凭证）号；桶间转移的两条流水共用同一个号。 示例： |
has_more | boolean | 必填 | 是否还有下一页。 示例： |
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通用 | 上游或平台依赖故障，平台无法确认本次请求是否已生效 | 同上 |
注意事项
amount有符号：正数增加该余额桶，负数减少；桶间转移是同一ledger_transaction_id下一减一增两条流水。- 同时给出
occurred_at（发生）与booked_at（记账）；created_gte/created_lt作用于booked_at。 - 迟到的事实按实际记账时间出现，不改写历史流水。