POST /v1/payments/{uid}/refund
可多次部分退。服务端用一条带条件的 UPDATE 校验 captured_amount - refunded_amount >= amount,
并发重复提交不会超退;超出时返回 409,不会静默截断。
路径参数
请求头
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"
}