跳到正文
PayHub开发者文档

查询收银会话

契约 v1.0.0

getCheckoutSession
GET/v1/checkout/sessions/{session_id}
所需权限payments:read

服务端查询收银会话。completed 只在关联 Payment 成功后出现；expired 只表示不再允许新提交，不代表支付失败。 商户履约必须以 Payment 状态或经验签的通知为准，不能依据浏览器回跳。

请求头

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

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

请求示例

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

需要替换的占位符

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

说明

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

响应

收银会话。

JSON
{
  "id": "cs_demo_001",
  "payment_id": "pay_demo_008",
  "status": "open",
  "checkout_url": "https://pay.payhub.example/checkout/<SHORT_LIVED_TOKEN>",
  "expires_at": "2026-09-23T09:30:00Z",
  "return_url": "https://merchant.example/payment/return",
  "cancel_url": "https://merchant.example/payment/cancel",
  "locale": "zh-CN",
  "created_at": "2026-09-23T09:00:00Z",
  "request_id": "req_demo_020"
}

需要替换的占位符

  • <SHORT_LIVED_TOKEN>：平台返回的短时凭据，原样使用，不要记录

响应字段

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

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

收银会话号。

示例：cs_demo_002

payment_id
string必填

关联的 Payment。

示例：pay_demo_002

status
string必填

收银会话状态。

  • open：可提交支付
  • completed：仅在关联 Payment 成功后出现
  • expired：不再允许新提交；不代表关联支付失败
  • open：可提交支付
  • completed：仅在关联 Payment 成功后出现
  • expired：不再允许新提交；不代表关联支付失败
  • 将来可能新增取值；不认识的状态不要当作成功。

示例：open

checkout_url
string(uri)必填

收银页地址，携带只绑定本会话的短时凭据，不含商户服务端密钥。只用于让付款人浏览器整页跳转：不要写入日志、分析工具或错误上报，也不要分享给他人。

示例：https://pay.payhub.example/checkout/<SHORT_LIVED_TOKEN>

expires_at
string(date-time)必填

会话失效时间，创建时确定：最长 30 分钟（平台可调短）且不超过订单剩余可支付期。过期后的只读期内（创建时确定，默认且最长 24 小时）付款人仍可用原链接查看会话与支付结果（只读，不能提交），之后链接失效。

示例：2026-09-23T09:30:00Z

return_url
string(uri)必填

支付结束后的商户返回地址。

示例：https://merchant.example/payment/return

cancel_url
string(uri)可为空必填

付款人点击“返回商户”时的地址；点击它不等于撤销已提交的扣款。未提供时为 null。

示例：https://merchant.example/payment/cancel

locale
string必填

收银页语言。

示例：zh-CN

created_at
string(date-time)必填

创建时间。

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

注意事项

  • completed 只在关联支付成功后出现。
  • expired 只表示会话不再接受新提交，不代表支付失败；会话过期时可能仍有支付在处理。
  • 过期后的只读期内（默认且最长 24 小时），付款人仍可用原链接查看会话与支付结果（只读，不能提交），之后链接失效。
  • 履约以支付状态或经验签的通知为准，不依据浏览器回跳，见履约规则。
这页有帮助吗？