查询退款列表
契约 v1.0.0
listRefunds/v1/refunds按原支付、商户退款号和状态查询当前商户、当前环境的退款。 按创建时间倒序、同一时间再按 id 倒序稳定排序，使用游标分页；created_gte 含、created_lt 不含。 平台异常退款（平台向持卡人原路退还重复扣款或金额不符多扣的款项）不通过开放 API 返回，查询返回 404，也不计入 Payment 的 refunded_amount、refund_status。
请求头
| 请求头 | 必填 | 格式 | 说明 |
|---|---|---|---|
| Authorization | 是 | Bearer <API_KEY> | 服务端密钥，只能在商户服务端使用；商户与环境由密钥推导。缺失、无效、撤销或过期返回 401。 |
查询参数
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
payment_id | string | 否 | 按原支付号过滤。 约束： 示例： |
merchant_refund_no | string | 否 | 按商户退款号精确匹配。 约束： 示例： |
status | string | 否 | 按退款状态过滤。
示例： |
limit | integer | 否 | 每页条数，默认 20，最大 100。 约束： |
cursor | string | 否 | 上一页响应中的 next_cursor。不透明字符串，客户端不得解析或拼接；须与首页使用相同的过滤条件。 约束： |
created_gte | string(date-time) | 否 | 创建时间下界（含），带时区的 ISO 8601。 示例： |
created_lt | string(date-time) | 否 | 创建时间上界（不含），带时区的 ISO 8601。 示例： |
请求示例
curl -X GET 'https://api.payhub.bbpays.site/v1/refunds?limit=20' \
-H 'Authorization: Bearer <TEST_SERVER_API_KEY>'需要替换的占位符
<TEST_SERVER_API_KEY>：测试环境服务端 API Key：在商户后台「API Key」页面创建
说明
服务端 API Key 只能在你的服务端使用，文档站不提供在线调试。获取测试 Key：商户后台 API Key（在新标签页打开商户后台）（测试环境；需要所有者、管理员或开发者）
响应
退款列表。
{
"data": [
{
"id": "ref_demo_001",
"version": 1,
"payment_id": "pay_demo_001",
"merchant_refund_no": "REFUND-DEMO-001",
"amount": 2500,
"currency": "USD",
"status": "succeeded",
"reason": "requested_by_customer",
"returned_amount": 0,
"failure": null,
"metadata": {
"ticket": "CS-DEMO-001"
},
"created_at": "2026-09-24T02:00:00Z",
"completed_at": "2026-09-24T02:00:09Z"
},
{
"id": "ref_demo_003",
"version": 1,
"payment_id": "pay_demo_001",
"merchant_refund_no": "REFUND-DEMO-003",
"amount": 1000,
"currency": "USD",
"status": "processing",
"reason": "requested_by_customer",
"returned_amount": 0,
"failure": null,
"metadata": {
"ticket": "CS-DEMO-001"
},
"created_at": "2026-09-24T01:00:00Z",
"completed_at": null
}
],
"has_more": false,
"next_cursor": null,
"request_id": "req_demo_027"
}响应字段
分页列表：data 为对象数组，has_more 为 true 时用 next_cursor 继续翻页。 字段说明见 对象小节。
| 名称 | 类型 | 必填 | 说明 |
|---|---|---|---|
data | array<Refund> | 必填 | |
id | string | 必填 | 平台退款号。 示例： |
version | integer(int64) | 必填 | 对象版本，每次有效业务变更递增（状态、失败原因、退回金额）。比较版本来丢弃旧事件，不要按状态名排序。 约束： 示例： |
payment_id | string | 必填 | 原支付号。 示例： |
merchant_refund_no | string | 必填 | 商户退款号，同一商户同一环境内唯一。 示例： |
amount | integer(int64) | 必填 | 退款本金，最小货币单位。 约束： 示例： |
currency | string | 必填 | 退款币种，继承原支付。 约束： 示例： |
status | string | 必填 | 退款状态。
示例： |
reason | string | 必填 | 退款原因。 示例： |
returned_amount | integer(int64) | 必填 | 退款成功后被真实退回的本金累计。 约束： 示例： |
failure | RefundFailure可为空 | 必填 | status 为 failed 或 rejected 时的原因，否则为 null。 |
metadata | object | 否 | 商户自定义键值，最多 20 个键；键最长 40 字符，值为最长 200 字符的字符串。禁止放入卡号等敏感数据，平台会做检查并拒绝。 约束： 示例： |
created_at | string(date-time) | 必填 | 受理时间。 示例： |
completed_at | string(date-time)可为空 | 必填 | 进入 succeeded、failed、rejected 或 canceled 的时间；尚未结束时为 null。 示例： |
has_more | boolean | 必填 | 是否还有下一页。 示例： |
next_cursor | string可为空 | 必填 | 下一页游标；没有下一页时为 null。 示例： |
request_id | string | 必填 | 本次请求的唯一标识。 示例： |
可能的错误码
| 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通用 | 上游或平台依赖故障，平台无法确认本次请求是否已生效 | 同上 |
注意事项
- 可按原支付、商户退款号与状态过滤；排序与分页规则同支付列表。
- 平台异常退款（平台向持卡人原路退还重复扣款或金额不符多扣的款项）不出现在列表中，也不计入支付的
refunded_amount、refund_status；平台另以站内信和邮件通知你。