跳到正文
PayHub开发者文档

查询结算单详情

契约 v1.0.0

getSettlement
GET/v1/settlements/{settlement_id}
所需权限finance:read

finance:read 默认不在开发者可授予范围内，需要所有者或管理员创建的 Key。

查询结算单及其来源明细。结算单固化明细、币种、费用、收款账户快照与总额，审核后不可编辑，账户变更不影响旧单。 payout_amount = reserved_amount - fee_amount。退款、拒付和保证金释放不重写历史结算单。

请求头

请求头必填格式说明
Authorization是Bearer <API_KEY>

服务端密钥，只能在商户服务端使用；商户与环境由密钥推导。缺失、无效、撤销或过期返回 401。

请求示例

curl
curl -X GET 'https://api.payhub.bbpays.site/v1/settlements/<SETTLEMENT_ID>' \
  -H 'Authorization: Bearer <TEST_SERVER_API_KEY>'

需要替换的占位符

  • <SETTLEMENT_ID>：按说明替换为你的实际值
  • <TEST_SERVER_API_KEY>：测试环境服务端 API Key：在商户后台「API Key」页面创建

说明

服务端 API Key 只能在你的服务端使用，文档站不提供在线调试。获取测试 Key：商户后台 API Key（在新标签页打开商户后台）（测试环境；需要所有者、管理员或开发者）

响应

结算单及明细。

结算单与明细：payout_amount = reserved_amount - fee_amount
{
  "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",
  "items": [
    {
      "source_type": "payment",
      "source_id": "pay_demo_001",
      "amount": 96500
    }
  ],
  "request_id": "req_demo_033"
}

响应字段

返回对象 字段说明见 对象小节。

名称类型必填说明
id
string必填

结算单号。

示例：stl_demo_001

currency
string必填

结算币种。

约束：格式 ^[A-Z]{3}$

示例：USD

period_start
string(date)必填

账期起始业务日期（含），按商户结算业务时区。

示例：2026-09-21

period_end
string(date)必填

账期结束业务日期（含）。

示例：2026-09-21

status
string必填

结算单状态。

  • pending_review：系统已生成，待审核；已原子占用所选商户余额
  • approved：复核通过，待执行
  • rejected：审核拒绝；释放占用
  • paying：已交付执行或打款结果未确定；保持占用
  • paid：已复核打款成功
  • failed：已明确本次没有成功付款；释放占用
  • canceled：尚未对外执行且按权限撤销；释放占用
  • returned：曾经成功的打款之后发生银行退汇
  • pending_review：系统已生成，待审核；已原子占用所选商户余额
  • approved：复核通过，待执行
  • rejected：审核拒绝；释放占用
  • paying：已交付执行或打款结果未确定；保持占用
  • paid：已复核打款成功
  • failed：已明确本次没有成功付款；释放占用
  • canceled：尚未对外执行且按权限撤销；释放占用
  • returned：曾经成功的打款之后发生银行退汇
  • 将来可能新增取值；不认识的状态不要当作成功。

示例：paid

reserved_amount
integer(int64)必填

本结算单从 available 转入 payout_pending 的余额占用 S。

约束：≥ 0

示例：8650

fee_amount
integer(int64)必填

结算手续费 F，默认 0。

约束：≥ 0

示例：0

payout_amount
integer(int64)必填

实际银行打款金额 = S - F。

约束：≥ 0

示例：8650

payout_account
PayoutAccount必填

结算单生成时固化的收款账户脱敏快照。

holder_name
string必填

账户持有人。

示例：Demo Merchant Ltd

bank_name
string必填

银行名称。

示例：Example Bank

account_last4
string必填

账号后四位。

约束：格式 ^[0-9A-Za-z]{4}$

示例：6789

payout_id
string可为空必填

对应的打款记录；尚未执行时为 null。

示例：po_demo_001

created_at
string(date-time)必填

生成时间。

示例：2026-09-22T02:00:00Z

items
array<SettlementItem>必填
source_type
string必填

来源类型，例如 payment、refund、adjustment。

示例：payment

source_id
string必填

来源对象 ID。

示例：pay_demo_001

amount
integer(int64)必填

计入本结算单的有符号金额，币种同结算单。

示例：8650

request_id
string必填

本次请求的唯一标识，用于排查与支持。

示例：req_demo_001

可能的错误码

HTTP错误码何时出现如何处理
404not_foundID 错误；用测试 Key 查询生产对象；查询平台异常退款（不通过开放 API 返回）核对 ID 与 Key 的环境；平台不会透露对象是否属于其他商户
401unauthenticated通用未带 Authorization；Key 复制不完整；轮换后旧 Key 已过期；Key 被撤销检查凭据，在 商户后台 API Key 页面 核对 Key 状态与环境
403forbidden通用只读 Key 创建退款；getEvent 缺少事件所属业务的读权限；请求来源 IP 不在 Key 的白名单时返回更具体的 ip_not_allowed使用具备所需 scope 的 Key；不要绕过限制
429rate_limited通用商户、Key 维度的频率限制；换 Key 不能绕过商户总限额等待 Retry-After 秒后用原幂等键重试
500internal_error通用—用原幂等键重试或按商户订单号 / 退款号查询；不能换键重扣
502 / 503upstream_unavailable通用上游或平台依赖故障，平台无法确认本次请求是否已生效同上

注意事项

  • items 是结算单的来源明细，amount 有符号。
  • payout_amount = reserved_amount - fee_amount。
  • payout_account 是生成时固化的脱敏快照：之后变更收款账户不影响旧结算单。
  • 退款、拒付、保证金释放不重写历史结算单。
这页有帮助吗？