跳到正文
PayHub开发者文档

查询退款

契约 v1.0.0

getRefund
GET/v1/refunds/{refund_id}
所需权限refunds:read

查询单笔退款。成功、失败与驳回都会形成可查询的状态并发送通知。 returned 表示曾确认成功的退款之后发生了真实资金退回，returned_amount 为已退回本金；原成功事实保留。 平台异常退款（平台向持卡人原路退还重复扣款或金额不符多扣的款项）不通过开放 API 返回，查询返回 404，也不计入 Payment 的 refunded_amount、refund_status。

请求头

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

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

请求示例

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

需要替换的占位符

  • <REFUND_ID>：创建退款返回的 id（ref_ 开头）
  • <TEST_SERVER_API_KEY>：测试环境服务端 API Key：在商户后台「API Key」页面创建

说明

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

响应

退款详情。

JSON
{
  "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",
  "request_id": "req_demo_025"
}

响应字段

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

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

平台退款号。

示例：ref_demo_001

version
integer(int64)必填

对象版本，每次有效业务变更递增（状态、失败原因、退回金额）。比较版本来丢弃旧事件，不要按状态名排序。

约束：≥ 1

示例：1

payment_id
string必填

原支付号。

示例：pay_demo_001

merchant_refund_no
string必填

商户退款号，同一商户同一环境内唯一。

示例：REFUND-DEMO-001

amount
integer(int64)必填

退款本金，最小货币单位。

约束：≥ 1

示例：4000

currency
string必填

退款币种，继承原支付。

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

示例：USD

status
string必填

退款状态。

  • pending_review：已受理，等待审核；保持资金占用
  • processing：已批准并提交，或正在确认上游结果；保持占用
  • succeeded：上游已确认退款成功；占用转为正式扣减
  • failed：已明确退款未成功；解除占用
  • rejected：审核驳回，未提交上游；解除占用
  • canceled：提交上游前被有权限的人员取消；解除占用
  • returned：曾确认成功的退款之后全部或部分资金被真实退回
  • pending_review：已受理，等待审核；保持资金占用
  • processing：已批准并提交，或正在确认上游结果；保持占用
  • succeeded：上游已确认退款成功；占用转为正式扣减
  • failed：已明确退款未成功；解除占用
  • rejected：审核驳回，未提交上游；解除占用
  • canceled：提交上游前被有权限的人员取消；解除占用
  • returned：曾确认成功的退款之后全部或部分资金被真实退回
  • 将来可能新增取值；不认识的状态不要当作成功。

示例：pending_review

reason
string必填

退款原因。

示例：requested_by_customer

returned_amount
integer(int64)必填

退款成功后被真实退回的本金累计。

约束：≥ 0

示例：0

failure
RefundFailure可为空必填

status 为 failed 或 rejected 时的原因，否则为 null。

code
string必填

失败原因码。

示例：refund_rejected

message
string必填

脱敏说明。

示例：退款申请未通过审核。

metadata
object否

商户自定义键值，最多 20 个键；键最长 40 字符，值为最长 200 字符的字符串。禁止放入卡号等敏感数据，平台会做检查并拒绝。

约束：最多 20 个键值最长 200

示例：{"business_order_type":"one_time_purchase"}

created_at
string(date-time)必填

受理时间。

示例：2026-09-23T10:00:00Z

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

进入 succeeded、failed、rejected 或 canceled 的时间；尚未结束时为 null。

示例：null

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

注意事项

  • returned 表示曾确认成功的退款之后发生了真实资金退回：原成功事实保留，returned_amount 为已退回本金。
  • failure 只在 failed、rejected 时出现。
  • 平台异常退款不通过本接口返回，查询返回 404。
这页有帮助吗？