● 退款 · /v1

退款

退款是独立资源,有自己的单号和状态。渠道可能几天后才拒退,退款的失败必须能单独查到。

退款

POST /v1/payments/{uid}/refund

可多次部分退。服务端用一条带条件的 UPDATE 校验 captured_amount - refunded_amount >= amount, 并发重复提交不会超退;超出时返回 409,不会静默截断。

路径参数

uid必填 string

请求头

Idempotency-Key必填 string 商户生成的唯一串(建议 UUID/ULID)。24 小时内重放同一 key 返回首次结果,不会产生第二笔。

请求体

amount integer 不传表示全额退
reason string

响应 201

uid string 退款单号:RF + yyyymmdd + 6 位序号
payment_uid string
reference_id string 你的退款单号,便于对账
amount integer
currency string
currency_exponent integer
status pending | succeeded | failed failed 是渠道事后拒退,可能在发起几天后才出现。必须订阅 refund.status_changed,不能只看发起时的同步响应
reason string
connector_code string
provider_refund_id string 渠道侧退款流水号,对账时和结算文件对
failure_code string 失败时填,取值同统一拒付码
created_at string<date-time>
finished_at string<date-time>

错误

409幂等键复用但请求体不同,或对象当前状态不允许该操作
请求
curl -X POST https://api.baton.example/v1/payments/{uid}/refund \
  -H "Authorization: Bearer sk_live_xxx" \
  -H "Idempotency-Key: 01J8ZQ4T7M2K9F3B" \
  -H "X-Timestamp: 1763280000" -H "X-Nonce: 7f3a" -H "X-Signature: v1=..." \
  -H "Content-Type: application/json" \
  -d '{
  "amount": 2000,
  "reason": "customer_request"
}'
响应 · 201
{
  "uid": "RF20261116000031",
  "payment_uid": "PY20261116000217A7F3",
  "amount": 2000,
  "currency": "USD",
  "currency_exponent": 2,
  "status": "pending",
  "reason": "customer_request",
  "connector_code": "adyen",
  "created_at": "2026-11-16T09:40:12Z"
}

退款列表

GET /v1/refunds

按支付单或时间段查。对账时以这里的 provider_refund_id 和渠道结算文件对,不要用支付单号去对退款。

Query 参数

payment_uid string
status pending | succeeded | failed
reference_id string
created_from string<date-time>
created_to string<date-time>
cursor string 上一页返回的 page.next_cursor
limit integer

响应 200

data object[]
└uid string 退款单号:RF + yyyymmdd + 6 位序号
└payment_uid string
└reference_id string 你的退款单号,便于对账
└amount integer
└currency string
└currency_exponent integer
└status pending | succeeded | failed failed 是渠道事后拒退,可能在发起几天后才出现。必须订阅 refund.status_changed,不能只看发起时的同步响应
└reason string
└connector_code string
└provider_refund_id string 渠道侧退款流水号,对账时和结算文件对
└failure_code string 失败时填,取值同统一拒付码
└created_at string<date-time>
└finished_at string<date-time>
page object
└next_cursor string
└has_more boolean
请求
curl -X GET https://api.baton.example/v1/refunds \
  -H "Authorization: Bearer sk_live_xxx"

查询退款

GET /v1/refunds/{uid}

一笔支付退了多次时,这是唯一能分清哪一次失败了的办法——支付单上的 refunded_amount 只是累加值。

路径参数

uid必填 string

响应 200

uid string 退款单号:RF + yyyymmdd + 6 位序号
payment_uid string
reference_id string 你的退款单号,便于对账
amount integer
currency string
currency_exponent integer
status pending | succeeded | failed failed 是渠道事后拒退,可能在发起几天后才出现。必须订阅 refund.status_changed,不能只看发起时的同步响应
reason string
connector_code string
provider_refund_id string 渠道侧退款流水号,对账时和结算文件对
failure_code string 失败时填,取值同统一拒付码
created_at string<date-time>
finished_at string<date-time>

错误

404对象不存在,或属于另一个环境 / 另一个商户
请求
curl -X GET https://api.baton.example/v1/refunds/{uid} \
  -H "Authorization: Bearer sk_live_xxx"