查询结算单列表
契约 v1.0.0
listSettlements/v1/settlementsfinance:read 默认不在开发者可授予范围内，需要所有者或管理员创建的 Key。
查询当前商户、当前环境的结算单。结算单由平台按已配置规则生成，首期不提供商户自助提现 API。 按创建时间倒序、同一时间再按 id 倒序稳定排序，使用游标分页；created_gte 含、created_lt 不含。
请求头
| 请求头 | 必填 | 格式 | 说明 |
|---|---|---|---|
| Authorization | 是 | Bearer <API_KEY> | 服务端密钥，只能在商户服务端使用；商户与环境由密钥推导。缺失、无效、撤销或过期返回 401。 |
查询参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
status | string | 否 | 按结算单状态过滤。
示例： |
currency | string | 否 | 按币种过滤。 约束： 示例： |
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/settlements?limit=20' \
-H 'Authorization: Bearer <TEST_SERVER_API_KEY>'需要替换的占位符
<TEST_SERVER_API_KEY>：测试环境服务端 API Key：在商户后台「API Key」页面创建
说明
服务端 API Key 只能在你的服务端使用，文档站不提供在线调试。获取测试 Key：商户后台 API Key（在新标签页打开商户后台）（测试环境；需要所有者、管理员或开发者）
响应
结算单列表。
{
"data": [
{
"id": "stl_demo_001",
"currency": "USD",
"period_start": "2026-09-23",
"period_end": "2026-09-23",
"status": "paid",
"reserved_amount": 96500,
"fee_amount": 500,
"payout_amount": 96000,
"payout_account": {
"holder_name": "Demo Merchant Ltd",
"bank_name": "Example Bank",
"account_last4": "6789"
},
"payout_id": "po_demo_001",
"created_at": "2026-09-24T01:00:00Z"
}
],
"has_more": false,
"next_cursor": null,
"request_id": "req_demo_032"
}响应字段
分页列表：data 为对象数组，has_more 为 true 时用 next_cursor 继续翻页。 字段说明见 对象小节。
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
data | array<Settlement> | 必填 | |
id | string | 必填 | 结算单号。 示例： |
currency | string | 必填 | 结算币种。 约束： 示例： |
period_start | string(date) | 必填 | 账期起始业务日期（含），按商户结算业务时区。 示例： |
period_end | string(date) | 必填 | 账期结束业务日期（含）。 示例： |
status | string | 必填 | 结算单状态。
示例： |
reserved_amount | integer(int64) | 必填 | 本结算单从 available 转入 payout_pending 的余额占用 S。 约束： 示例： |
fee_amount | integer(int64) | 必填 | 结算手续费 F，默认 0。 约束： 示例： |
payout_amount | integer(int64) | 必填 | 实际银行打款金额 = S - F。 约束： 示例： |
payout_account | PayoutAccount | 必填 | 结算单生成时固化的收款账户脱敏快照。 |
payout_id | string可为空 | 必填 | 对应的打款记录；尚未执行时为 null。 示例： |
created_at | string(date-time) | 必填 | 生成时间。 示例： |
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通用 | 上游或平台依赖故障，平台无法确认本次请求是否已生效 | 同上 |
注意事项
- 结算单由平台按已配置的规则生成，首期不提供自助提现 API。
payout_amount = reserved_amount - fee_amount；payout_account是生成时的脱敏快照。