API 参考
English退款接口
创建退款与查询退款。卡类退款为全额退款，且需审核后完成。
创建退款
POST/api/v1/refunds/create请求字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
original_order_no | string | 二选一 | 原 HansaPay 系统支付订单号 |
original_merchant_order_no | string | 二选一 | 原商户支付订单号 |
merchant_refund_no | string | 是 | 商户退款单号，最长 64 个字符 |
refund_amount | string | 是 | 退款金额，币种与原订单一致 |
reason | string | 否 | 退款原因 |
notify_url | string | 否 | 退款通知地址。不传则不发送退款通知 |
metadata | string | 否 | 商户透传参数，在退款通知中回传 |
说明：
- 卡、Apple Pay 与 Google Pay 支付仅支持一次全额退款。部分金额会被拒绝，返回
This payment channel does not support partial refunds; only full refunds are allowed - 此类退款初始为
PENDING，审核后才完成；HansaPay 每隔几分钟检查一次，完成后发送refund.updated。30 分钟后上游仍无记录的退款会变为FAILED - Cash App 退款即时完成，且支持部分退款
- 退款处理中时，退款金额与退款手续费会从可用余额中冻结，失败则解冻。余额不足以覆盖时，退款会被拒绝
- 被拒绝的退款同样占用其
merchant_refund_no；被拒绝的退款记录为FAILED - 退款状态：
PENDING/SUCCESS/FAILED
成功 data
| 字段 | 类型 | 说明 |
|---|---|---|
refund_no | string | HansaPay 系统退款单号 |
merchant_refund_no | string | 商户退款单号 |
original_order_no | string | 原 HansaPay 系统订单号 |
original_merchant_order_no | string | 原商户订单号 |
status | string | 退款状态 |
refund_amount | object | 退款金额 |
created_at | string | 创建时间 |
完整成功响应示例
{
"code": 0,
"msg": "success",
"data": {
"refund_no": "R202406240001",
"merchant_refund_no": "MR202406240001",
"original_order_no": "O202406240001",
"original_merchant_order_no": "M202406240001",
"status": "PENDING",
"refund_amount": {
"currency": "USD",
"value": "99.99"
},
"created_at": "2026-06-24T11:00:00+08:00"
}
}查询退款
POST/api/v1/refunds/query请求字段
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
refund_no | string | 二选一 | HansaPay 系统退款单号 |
merchant_refund_no | string | 二选一 | 商户退款单号 |
成功 data
| 字段 | 类型 | 说明 |
|---|---|---|
refund_no | string | HansaPay 系统退款单号 |
merchant_refund_no | string | 商户退款单号 |
original_order_no | string | 原 HansaPay 系统订单号 |
original_merchant_order_no | string | 原商户订单号 |
status | string | 退款状态 |
refund_amount | object | 退款金额 |
reason | string | 退款原因 |
created_at | string | 创建时间 |
updated_at | string | 更新时间 |
完整成功响应示例
{
"code": 0,
"msg": "success",
"data": {
"refund_no": "R202406240001",
"merchant_refund_no": "MR202406240001",
"original_order_no": "O202406240001",
"original_merchant_order_no": "M202406240001",
"status": "SUCCESS",
"refund_amount": {
"currency": "USD",
"value": "99.99"
},
"reason": "customer requested",
"created_at": "2026-06-24T11:00:00+08:00",
"updated_at": "2026-06-24T11:00:05+08:00"
}
}