查询支付详情

契约 v1.0.0

本页目录

getPayment

GET/v1/payments/{payment_id}

所需权限payments:read

返回 Payment 的当前已知事实与结果确认程度。收到旧事件或怀疑状态冲突时，以本接口的最新状态和 version 为准。不属于当前商户或环境的对象返回 404，不暴露其存在。查询只读取平台已记录的状态，不会触发向上游的查询。

请求头

请求头	必填	格式	说明
Authorization	是	Bearer <API_KEY>	服务端密钥，只能在商户服务端使用；商户与环境由密钥推导。缺失、无效、撤销或过期返回 401。

请求示例

curl

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

需要替换的占位符

<PAYMENT_ID>：创建支付返回的 id（pay_ 开头）
<TEST_SERVER_API_KEY>：测试环境服务端 API Key：在商户后台「API Key」页面创建

说明

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

响应

支付详情。

支付成功

{
  "id": "pay_demo_001",
  "merchant_order_no": "ORDER-DEMO-001",
  "environment": "test",
  "amount": 10000,
  "currency": "USD",
  "status": "succeeded",
  "resolution_status": "known",
  "captured_amount": 10000,
  "refunded_amount": 0,
  "refund_returned_amount": 0,
  "refund_reserved_amount": 0,
  "refund_status": "none",
  "authentication_status": "authenticated",
  "reconciliation_status": "pending",
  "upstream_receipt_status": "not_received",
  "latest_attempt_id": "pat_demo_001",
  "attempt_count": 1,
  "version": 4,
  "next_action": null,
  "failure": null,
  "description": "示例订单",
  "customer_reference": "CUSTOMER-DEMO-001",
  "metadata": {
    "business_order_type": "one_time_purchase"
  },
  "card": {
    "brand": "visa",
    "last4": "1234"
  },
  "created_at": "2026-09-23T09:00:00Z",
  "succeeded_at": "2026-09-23T09:04:30Z",
  "expires_at": "2026-09-23T09:30:00Z",
  "request_id": "req_demo_028"
}

响应字段

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

名称	类型	必填	说明
`id`	string	必填	平台支付号。示例：`pay_demo_001`
`merchant_order_no`	string	必填	商户订单号，按原值区分大小写。示例：`ORDER-DEMO-001`
`environment`	string	必填	环境：test 为测试，live 为生产。测试与生产对象相互隔离。 `test` `live` 将来可能新增取值；不认识的状态不要当作成功。示例：`test`
`amount`	integer(int64)	必填	订单金额，最小货币单位。首次提交上游后不可修改。约束：`≥ 1` 示例：`10000`
`currency`	string	必填	大写三字母币种代码。约束：`格式 ^[A-Z]{3}$` 示例：`USD`
`status`	string	必填	Payment 状态。客户端不得把未知状态当作成功。 created：订单已建立，尚未提交有效扣款尝试；有效期内允许新尝试 processing：已提交，正在处理或结果尚未确认；不允许新尝试 requires_action：当前尝试需要付款人完成认证等动作；不允许新尝试 failed：最近一次尝试已明确失败；不是终态，满足期限、次数与风控条件时可显式重试 succeeded：已确认支付成功 canceled：已确认安全取消 expired：没有未解决的尝试且订单已到期关闭 `created`：订单已建立，尚未提交有效扣款尝试；有效期内允许新尝试 `processing`：已提交，正在处理或结果尚未确认；不允许新尝试 `requires_action`：当前尝试需要付款人完成认证等动作；不允许新尝试 `failed`：最近一次尝试已明确失败；不是终态，满足期限、次数与风控条件时可显式重试 `succeeded`：已确认支付成功 `canceled`：已确认安全取消 `expired`：没有未解决的尝试且订单已到期关闭将来可能新增取值；不认识的状态不要当作成功。示例：`requires_action`
`resolution_status`	string	必填	结果确认程度。 known：结果已确认 needs_query：结果未知，平台正在用原标识向上游查证 manual_review：超过自动查询窗口，转人工跟进；不会自动判失败 `known`：结果已确认 `needs_query`：结果未知，平台正在用原标识向上游查证 `manual_review`：超过自动查询窗口，转人工跟进；不会自动判失败将来可能新增取值；不认识的状态不要当作成功。示例：`known`
`captured_amount`	integer(int64)	必填	已确认扣款金额；成功时等于 amount。约束：`≥ 0` 示例：`0`
`refunded_amount`	integer(int64)	必填	已确认的有效退款本金，即成功退款累计减去已确认的退款退回；不含处理中的退款，也不含平台异常退款。约束：`≥ 0` 示例：`0`
`refund_returned_amount`	integer(int64)	必填	已确认退回的退款本金累计。约束：`≥ 0` 示例：`0`
`refund_reserved_amount`	integer(int64)	必填	审核中及处理中退款的本金占用。约束：`≥ 0` 示例：`0`
`refund_status`	string	必填	按有效退款本金 refunded_amount 派生的退款汇总状态：none、partial、full。 `none` `partial` `full` 将来可能新增取值；不认识的状态不要当作成功。示例：`none`
`authentication_status`	string可为空	必填	当前尝试的 3DS 认证状态，取认证会话状态：not_required、pending、challenge、authenticated、failed、abandoned、expired，须容忍新增取值。认证成功（authenticated）不等于扣款成功，不要据此判断支付结果。尚无尝试或未进入认证时为 null。示例：`challenge`
`reconciliation_status`	ReconciliationStatus	必填	平台资金处理进度，仅供对账参考，不代表支付是否成功，也不代表何时打款。 `pending` `matched` `difference` `resolved` 将来可能新增取值；不认识的状态不要当作成功。
`upstream_receipt_status`	UpstreamReceiptStatus	必填	平台资金处理进度，仅供对账参考，不代表支付是否成功，也不代表何时打款。 `not_received` `partially_received` `received` `reversed` 将来可能新增取值；不认识的状态不要当作成功。
`latest_attempt_id`	string可为空	必填	最近一次支付尝试号；尚未提交尝试时为 null。示例：`pat_demo_001`
`attempt_count`	integer(int32)	必填	已发起的尝试次数；默认最多 3 次。约束：`≥ 0` 示例：`1`
`version`	integer(int64)	必填	对象版本，每次有效业务变更递增。比较版本来丢弃旧事件，不要按状态名排序。约束：`≥ 1` 示例：`2`
`next_action`	NextAction可为空	必填	status=requires_action 时需要付款人完成的动作，其他情况为 null。
`type`	string	必填	首期公共 API 只开放 redirect_to_url。客户端须容忍未来新增的类型。 `redirect_to_url` 将来可能新增取值；不认识的状态不要当作成功。示例：`redirect_to_url`
`authentication_session_id`	string	必填	认证会话号，关联具体的支付尝试。示例：`auth_demo_001`
`url`	string(uri)	必填	平台认证承载页地址。示例：`https://pay.payhub.example/auth/<SHORT_LIVED_TOKEN>`
`expires_at`	string(date-time)	必填	认证访问的失效时间（最长 10 分钟）。示例：`2026-09-23T09:10:00Z`
`failure`	PaymentFailure可为空	必填	latest_attempt_id 所指尝试明确失败时的原因，否则为 null。
`code`	string	必填	失败原因码。示例：`card_declined`
`message`	string	必填	脱敏说明。示例：`发卡行拒绝了该交易。`
`attempt_id`	string	必填	失败的支付尝试号。示例：`pat_demo_001`
`description`	string	否	订单摘要。约束：`最长 256` 示例：`示例订单`
`customer_reference`	string	否	商户侧客户标识。约束：`最长 128` 示例：`CUSTOMER-DEMO-001`
`metadata`	object	否	商户自定义键值，最多 20 个键；键最长 40 字符，值为最长 200 字符的字符串。禁止放入卡号等敏感数据，平台会做检查并拒绝。约束：`最多 20 个键值最长 200` 示例：`{"business_order_type":"one_time_purchase"}`
`card`	CardSummary可为空	必填	最近一次尝试所用卡的脱敏信息；尚无卡信息时为 null。
`brand`	string	必填	卡品牌。示例：`visa`
`last4`	string	必填	卡号后四位。约束：`格式 ^[0-9]{4}$` 示例：`1234`
`created_at`	string(date-time)	必填	创建时间。示例：`2026-09-23T09:00:00Z`
`succeeded_at`	string(date-time)可为空	必填	确认支付成功的时间；未成功时为 null。示例：`null`
`expires_at`	string(date-time)	必填	可发起新尝试的截止时间，创建时确定（默认创建后 30 分钟，平台可在 5–120 分钟之间调整，以本字段为准）。到期只关闭新的付款入口，不否定已提交的支付。示例：`2026-09-23T09:30:00Z`
`request_id`	string	必填	本次请求的唯一标识，用于排查与支持。示例：`req_demo_001`

可能的错误码

HTTP	错误码	何时出现	如何处理
404	not_found	ID 错误；用测试 Key 查询生产对象；查询平台异常退款（不通过开放 API 返回）	核对 ID 与 Key 的环境；平台不会透露对象是否属于其他商户
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通用	上游或平台依赖故障，平台无法确认本次请求是否已生效	同上

注意事项

返回当前已知事实与结果确认程度（resolution_status）。收到旧事件或怀疑冲突时，以本接口返回的状态与 version 为准。
查询只读取平台已记录的状态，不会触发向上游的查询；查询频率建议见查单频率。
不属于当前商户或当前环境的对象返回 404，平台不透露对象是否存在。

相关事件：payment.succeeded、payment.failed、payment.corrected
结果未知时查单
错误码与 HTTP 状态

这页有帮助吗？

查询支付详情

请求头

请求示例

响应

响应字段

可能的错误码

注意事项

相关