跳到正文
PayHub开发者文档

查询打款结果

契约 v1.0.0

getPayout
GET/v1/payouts/{payout_id}
所需权限finance:read

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

查询一次结算对应的对外打款。unknown 表示暂时无法确认银行结果：对应结算单保持 paying，不释放资金，平台先查证、不重复打款。 returned 表示曾成功的打款之后发生银行退汇，原成功记录保留。 开放 API 只能按 ID 查询打款：打款号取自结算单的 payout_id，没有打款列表接口，打款列表在商户后台查看。

请求头

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

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

请求示例

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

需要替换的占位符

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

说明

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

响应

打款记录。

JSON
{
  "id": "po_demo_001",
  "settlement_id": "stl_demo_001",
  "amount": 96000,
  "currency": "USD",
  "status": "succeeded",
  "reference": "PAYOUT-REF-DEMO-001",
  "executed_at": "2026-09-24T03:00:00Z",
  "completed_at": "2026-09-24T05:00:00Z",
  "request_id": "req_demo_034"
}

响应字段

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

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

打款记录号。

示例：po_demo_001

settlement_id
string必填

对应的结算单。

示例：stl_demo_001

amount
integer(int64)必填

打款金额，最小货币单位。

约束：≥ 1

示例：8650

currency
string必填

币种。

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

示例：USD

status
string必填

打款状态：created、processing、unknown、succeeded、failed、canceled、returned。 unknown 时对应结算单保持 paying，不自动释放资金。

  • created
  • processing
  • unknown
  • succeeded
  • failed
  • canceled
  • returned
  • 将来可能新增取值；不认识的状态不要当作成功。

示例：succeeded

reference
string必填

平台打款唯一参考号，不复用于新的转账。

示例：PAYOUT-REF-DEMO-001

executed_at
string(date-time)可为空必填

交付执行时间；尚未执行时为 null。

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

completed_at
string(date-time)可为空必填

经复核确认成功或失败的时间；尚未确认时为 null。

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

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通用上游或平台依赖故障，平台无法确认本次请求是否已生效同上

注意事项

  • 开放 API 只能按 ID 查询打款：打款号取自结算单的 payout_id；没有打款列表接口，列表在商户后台查看（打款记录（在新标签页打开商户后台）（需要所有者、管理员或财务））。
  • unknown 表示暂时无法确认银行结果：对应结算单保持 paying、资金不释放，平台先查证，不会重复打款。
  • returned 表示成功后发生了银行退汇，原成功记录保留。
这页有帮助吗？