开发者文档
官网控制台

创建 Refund

POST
/openapi/v1/payment-intents/{paymentIntentId}/refunds

为指定 Payment Intent 创建退款。支持部分退款和全额退款。不传 amount 时，退还剩余可退金额。退款先进入 PENDING_APPROVAL，运营确认后执行。

成功返回 HTTP 200。

鉴权

bearerAuth
header鉴权Bearer <令牌>

通过 POST /oauth2/token 获取的 access_token。请求头格式为 Authorization: Bearer {accessToken}。

路径参数

paymentIntentId*string

Payment Intent ID，如 pi_MNOL0POUV8IDPXCD

Header 参数

Idempotency-Key*string

唯一请求标识，建议使用 UUID 或业务唯一流水号。同一业务请求重试时复用相同的 Key，不同业务请求必须使用不同的 Key

请求体

application/json
  1. body
destinationAddress*string

退款目标链上地址，必须在原付款的网络上

amount?string

退款金额，标准单位，按 Payment Intent 的币种计。小数位不能超过币种精度。不传则退剩余全额

reason?RefundReason

退款原因。

  • DUPLICATE: 重复支付或重复订单
  • FRAUDULENT: 欺诈或风险原因
  • REQUESTED_BY_CUSTOMER: 客户主动要求退款
  • OTHER: 其他原因
可选值"DUPLICATE""FRAUDULENT""REQUESTED_BY_CUSTOMER""OTHER"
notes?string

退款备注

metadata?

商户自定义元数据

响应体

返回 Refund 对象。

application/json
  1. response
code?integer

业务状态码

message?string
traceId?string

请求追踪 ID。联系技术支持时请提供

data?

Refund 对象。

curl -X POST 'https://api.test.stabofx.com/openapi/v1/payment-intents/string/refunds' \  -H 'Idempotency-Key: pi_20260511_0001' \  -H 'Content-Type: application/json' \  -d '{  "destinationAddress": "0x97535e309484738738877fa6f9a3bb8c62eae19a",  "amount": "10.00",  "reason": "REQUESTED_BY_CUSTOMER",  "notes": "Customer requested a partial refund.",  "metadata": {    "orderId": "order_202605110001"  }}'
响应示例
{  "code": 200,  "message": "OK",  "traceId": "6a0188c437f0973a0e940d0586d01c9e",  "data": {    "refundId": "re_IFWNVQP0O6EHB6KV",    "paymentIntentId": "pi_TZA3DEDJUNZLTUJ2",    "amount": "10.00",    "currency": "USD",    "status": "PENDING_APPROVAL",    "reason": "REQUESTED_BY_CUSTOMER",    "notes": "Customer requested a partial refund.",    "metadata": {      "orderId": "order_202605110001"    },    "createdAt": "2026-05-11T17:18:41+08:00"  }}