查询支付列表

契约 v1.0.0

本页目录

listPayments

GET/v1/payments

所需权限payments:read

按商户订单号、状态和创建时间查询当前商户、当前环境的支付。按创建时间倒序、同一时间再按 id 倒序稳定排序，使用游标分页；created_gte 含、created_lt 不含。

请求头

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

查询参数

名称	类型	必填	说明
`merchant_order_no`	string	否	按商户订单号精确匹配，区分大小写。约束：`格式 ^[A-Za-z0-9._:-]{1,64}$` 示例：`ORDER-DEMO-001`
`status`	string	否	按支付状态过滤。 `created`：订单已建立，尚未提交有效扣款尝试；有效期内允许新尝试 `processing`：已提交，正在处理或结果尚未确认；不允许新尝试 `requires_action`：当前尝试需要付款人完成认证等动作；不允许新尝试 `failed`：最近一次尝试已明确失败；不是终态，满足期限、次数与风控条件时可显式重试 `succeeded`：已确认支付成功 `canceled`：已确认安全取消 `expired`：没有未解决的尝试且订单已到期关闭将来可能新增取值；不认识的状态不要当作成功。示例：`requires_action`
`limit`	integer	否	每页条数，默认 20，最大 100。约束：`1–100默认 20`
`cursor`	string	否	上一页响应中的 next_cursor。不透明字符串，客户端不得解析或拼接；须与首页使用相同的过滤条件。约束：`长度 1–512`
`created_gte`	string(date-time)	否	创建时间下界（含），带时区的 ISO 8601。示例：`2026-09-23T00:00:00Z`
`created_lt`	string(date-time)	否	创建时间上界（不含），带时区的 ISO 8601。示例：`2026-09-24T00:00:00Z`

请求示例

curl

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

需要替换的占位符

<TEST_SERVER_API_KEY>：测试环境服务端 API Key：在商户后台「API Key」页面创建

说明

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

响应

支付列表。

第一页（还有更多：用 next_cursor 并带相同过滤条件继续）

{
  "data": [
    {
      "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"
    },
    {
      "id": "pay_demo_002",
      "merchant_order_no": "ORDER-DEMO-002",
      "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": "not_required",
      "reconciliation_status": "pending",
      "upstream_receipt_status": "not_received",
      "latest_attempt_id": "pat_demo_002",
      "attempt_count": 1,
      "version": 3,
      "next_action": null,
      "failure": null,
      "description": "示例订单",
      "customer_reference": "CUSTOMER-DEMO-002",
      "metadata": {
        "business_order_type": "one_time_purchase"
      },
      "card": {
        "brand": "visa",
        "last4": "1234"
      },
      "created_at": "2026-09-23T08:58:00Z",
      "succeeded_at": "2026-09-23T08:58:06Z",
      "expires_at": "2026-09-23T09:28:00Z"
    }
  ],
  "has_more": true,
  "next_cursor": "cur_demo_opaque_001",
  "request_id": "req_demo_029"
}

响应字段

分页列表：data 为对象数组，has_more 为 true 时用 next_cursor 继续翻页。字段说明见对象小节。

名称	类型	必填	说明
`data`	array<Payment>	必填
`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。
`failure`	PaymentFailure可为空	必填	latest_attempt_id 所指尝试明确失败时的原因，否则为 null。
`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。
`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`
`has_more`	boolean	必填	是否还有下一页。示例：`false`
`next_cursor`	string可为空	必填	下一页游标；没有下一页时为 null。示例：`null`
`request_id`	string	必填	本次请求的唯一标识。示例：`req_demo_001`

可能的错误码

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

注意事项

可按 merchant_order_no（精确匹配、区分大小写）、status、created_gte（含）/ created_lt（不含）过滤。
按 created_at 倒序、同一时刻按 id 倒序；翻页时带上与首页相同的过滤条件，见分页。

错误码与 HTTP 状态

这页有帮助吗？