申请退款
本接口为回调接口,由 APP 服务端实现并提供给 SUD 调用,SUD 将通过此接口向 APP 服务端发起退款申请。
接口说明
接口英文名 pay.refund
功能描述 申请退款。SUD OP SVR 通过此回调接口向 APP 服务端发起退款请求,APP 服务端受理后返回退款单号。
注意:本接口强制要求服务通信二次加密和签名:回调请求必须验签通过后才能处理业务,可有效防止数据篡改与泄露。
调用方式
HTTPS 调用
http
POST <APP 自定义回调地址>请求参数 - Body
| 属性 | 类型 | 默认值 | 必填 | 说明 |
|---|---|---|---|---|
| env | number | 是 | 环境配置 0-正式环境, 1-测试环境 | |
| sud_refund_no | string | 是 | SUD 退款单号 | |
| sud_trade_no | string | 是 | SUD 业务订单号 | |
| reason | string | 是 | 退款原因 |
返回值
返回的 JSON 数据包
| 属性 | 类型 | 说明 |
|---|---|---|
| errcode | int32 | 错误码 |
| errmsg | string | 错误信息 |
| refund_id | string | 【退款单号】申请退款受理成功时,该笔退款单在支付侧生成的唯一标识 |
| sud_trade_no | string | SUD 业务订单号 |
| sud_refund_no | string | SUD 退款单号 |
调用示例
说明:以下请求示例为解密后的业务数据,实际收到的是密文并携带签名请求头,须先验签、解密后再按此结构解析;返回示例为加密前的业务数据,实际返回须先加密、再对密文签名。完整规范见回调签名加密。
请求数据示例
json
{
"env": 0,
"sud_refund_no": "sud_refund_20231024123456",
"sud_trade_no": "sud_20231024123456",
"reason": "用户申请退款"
}返回数据示例
json
{
"errcode": 0,
"errmsg": "ok",
"refund_id": "50300123420231024567890",
"sud_trade_no": "sud_20231024123456",
"sud_refund_no": "sud_refund_20231024123456"
}幂等说明
同一 sud_refund_no 视为同一笔退款。APP SVR 必须以 sud_refund_no 作为幂等键,重复调用时返回同一个 refund_id:
| 场景 | 要求 |
|---|---|
| 首次调用 | 受理退款并返回该笔退款的 refund_id |
| 重复调用 | 返回首次受理生成的同一 refund_id,errcode 返回 0,不得重复发起资金退回 |
| 首次响应超时后重试 | 按重复调用处理,仍返回同一 refund_id,不得生成第二笔退款单 |
| 首次退款仍在处理中 | 同样返回同一 refund_id;退款终态由 APP SVR 通过 pay.refundNotify 上报 |
重试时 SUD OP SVR 会重新生成
X-Sud-Timestamp与随机串并重新签名,sud_refund_no保持不变。
