收付款

退款

从开发者钱包对已支付的收款单全额或部分退款。

http

POST /open/v1/payments/{payment_id}/refunds
Idempotency-Key: 7a1f3c9e0b2d4e6f

json

{
  "out_refund_no": "R20261107-0001",
  "amount": "15.00",
  "reason": "用户取消"
}

字段	必填	说明
`out_refund_no`	✓	你的退款单号，`[A-Za-z0-9_-]{1,64}`，在环境内唯一
`amount`	✓	不超过收款单的 `amount − refunded_amount`
`reason`		最长 255，记录在订单中

规则

只有 PAID 的收款单可以退款（否则 REFUND_NOT_ALLOWED）。
退款同步完成：响应中 status: "SUCCEEDED"，资金退回原付款人。
从你的钱包扣除全部退款金额，手续费不退。余额不足返回 INSUFFICIENT_BALANCE。
可多次部分退款，直到 refunded_amount 等于 amount（超出返回 REFUND_AMOUNT_EXCEEDED）。
退款是一张独立订单：order_type: "REFUND"，parent_id 为收款单 id，同时发送 payment.refunded 回调。
收款单状态仍为 PAID，其 refunded_amount 增加。

json

{
  "id": "5a4b3c2d-1e0f-4a9b-8c7d-6e5f4a3b2c1d",
  "out_order_no": "R20261107-0001",
  "order_type": "REFUND",
  "parent_id": "0b7a9c62-3f1e-4a2b-9d6c-5e4f3a2b1c0d",
  "status": "SUCCEEDED",
  "amount": "15.00",
  "fee_amount": "0.00",
  "net_amount": "15.00",
  "currency": "USDT",
  "user_sub": "2f6c0d1e8a9b4c7d",
  "completed_at": "2026-11-07T10:00:00Z",
  "…": "…"
}

超时恢复

退款请求超时时，用相同的 Idempotency-Key 和请求体重试，或查询：

http

GET /open/v1/orders?out_order_no=R20261107-0001&order_type=REFUND

返回 ORDER_NOT_FOUND 表示未创建，可以安全重试。