退款申请
接口描述
业务通过统一退款接口发起退款申请
接口链接
URL地址：{payUrl}/api/refund/create_order
请求参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户ID | mchId | 是 | String(30) | 20001222 | 支付中心分配的商户号 |
| 支付订单号 | payOrderId | 是 | String(30) | P20160427210604000490 | 支付中心生成的原始订单号，与mchOrderNo二者传一即可 |
| 商户订单号 | mchOrderNo | 是 | String(30) | 20160427210604000490 | 商户生成的原始订单号，与payOrderId二者传一即可 |
| 商户退款单号 | mchRefundNo | 是 | String(30) | 20200727210612000129 | 商户生成的退款单号 |
| 退款金额 | amount | 是 | int | 100 | 退款金额,单位分 |
| 币种 | currency | 是 | String(3) | cny | 三位货币代码,人民币:cny |
| 客户端IP | clientIp | 否 | String(32) | 210.73.10.148 | 客户端IP地址 |
| 设备 | device | 否 | String(64) | ios10.3.1 | 客户端设备 |
| 附加参数 | extra | 否 | String(512) | 特定渠道发起时额外参数 | |
| 扩展参数1 | param1 | 否 | String(64) | 支付中心回调时原样返回 | |
| 扩展参数2 | param2 | 否 | String(64) | 支付中心回调时原样返回 | |
| 异步回调地址 | notifyUrl | 是 | String(128) | http://shop.xx.com/notify.htm | 退款结果异步回调URL |
| 渠道用户 | channelUser | 否 | String(256) | oIkQuwhPgPUgl-TvQ48_UUpZUwMs | 渠道用户信息 |
| 用户姓名 | userName | 否 | String(64) | 张三 | 用户姓名 |
| 备注 | remarkInfo | 否 | String(256) | 退款 | 备注信息 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
响应结果
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 返回状态码 | retCode | 是 | String(16) | 0 | 0-处理成功，其他-处理有误，详见错误码 |
| 返回信息 | retMsg | 否 | String(128) | 签名失败 | 具体错误原因，例如：签名失败、参数格式校验错误 |
以下字段在retCode=0 时有返回
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户ID | mchId | 是 | String(30) | 20001222 | 支付中心分配的商户号 |
| 应用ID | appId | 否 | String(30) | wx390ee383939c4fb2 | 应用ID |
| 退款单号 | refundOrderId | 是 | String(30) | R01201907231119090520000 | 返回支付系统退款单号 |
| 商户退款单号 | mchRefundNo | 是 | String(30) | 20200727210612000129 | 商户生成的退款单号 |
| 退款金额 | refundAmount | 是 | int | 100 | 退款金额,单位分 |
| 订单状态 | status | 是 | String(3) | 2 | 退款状态:0-订单生成,1-退款中,2-退款成功,3-退款失败 |
| 渠道订单号 | channelOrderNo | 否 | String wx20170910211043fb206e92260071822007 | 对应的第三方单号 | |
| 退款成功时间 | refundSuccTime | 否 | Long | 1505049094262 | 退款成功时间，精确到毫秒 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
查询订单
接口描述
业务系统通过查询退款订单接口获取最新的退款订单状态，并根据状态结果进一步处理业务逻辑。
接口链接
URL地址：{payUrl}/api/refund/query_order
请求参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户ID | mchId | 是 | String(30) | 1000000010 | 支付中心分配的商户号 |
| 平台退款单号 | refundOrderId | 是 | String(30) | R20160427210604000490 | 支付中心生成的退款单号，与mchRefundNo二者传一即可 |
| 商户退款单号 | mchRefundNo | 是 | String(30) | 20160427210604000490 | 商户生成的订单号，与refundOrderId二者传一即可 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
响应结果
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 返回状态码 | retCode | 是 | String(16) | 0 | 0-处理成功，其他-处理有误，详见错误码 |
| 返回信息 | retMsg | 否 | String(128) | 签名失败 | 具体错误原因，例如：签名失败、参数格式校验错误 |
以下字段在retCode=0 时有返回
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户ID | mchId | 是 | String(30) | 20001222 | 支付中心分配的商户号 |
| 应用ID | appId | 否 | String(30) | wx390ee383939c4fb2 | 应用ID |
| 商户退款单号 | mchRefundNo | 是 | String(30) | 20200727210612000129 | 商户生成的退款单号 |
| 退款金额 | refundAmount | 是 | int | 100 | 退款金额,单位分 |
| 订单状态 | status | 是 | String(3) | 2 | 退款状态:0-订单生成,1-退款中,2-退款成功,3-退款失败 |
| 渠道订单号 | channelOrderNo | 否 | String wx20170910211043fb206e92260071822007 | 对应的第三方单号 | |
| 退款成功时间 | refundSuccTime | 否 | Long | 1505049094262 | 退款成功时间，精确到毫秒 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
退款通知
接口描述
当退款完成时，支付中心会向商户的notifyUrl地址发起回调，通知退款状态。
接口链接
该链接是通过退款申请接口提交的参数notifyUrl设置，如果无法访问链接，业务系统将无法接收到支付中心的通知。
通知参数
| 字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
|---|---|---|---|---|---|
| 商户ID | mchId | 是 | String(30) | 20001222 | 支付中心分配的商户号 |
| 应用ID | appId | 否 | String(30) | wx390ee383939c4fb2 | 应用ID |
| 退款单号 | refundOrderId | 是 | String(30) | R01201907231119090520000 | 返回支付系统退款单号 |
| 商户退款单号 | mchRefundNo | 是 | String(30) | 20200727210612000129 | 商户生成的退款单号 |
| 退款金额 | refundAmount | 是 | int | 100 | 退款金额,单位分 |
| 订单状态 | status | 是 | String(3) | 2 | 退款状态:0-订单生成,1-退款中,2-退款成功,3-退款失败 |
| 渠道订单号 | channelOrderNo | 否 | String wx20170910211043fb206e92260071822007 | 对应的第三方单号 | |
| 退款成功时间 | refundSuccTime | 否 | Long | 1505049094262 | 退款成功时间，精确到毫秒 |
| 扩展参数1 | param1 | 否 | String(64) | 支付中心回调时原样返回 | |
| 扩展参数2 | param2 | 否 | String(64) | 支付中心回调时原样返回 | |
| 退款成功时间 | refundSuccTime | 否 | Long | 1505049094262 | 退款成功时间，精确到毫秒 |
| 通知类型 | backType | 是 | int | 1 | 通知类型，1-前台通知，2-后台通知 |
| 签名 | sign | 是 | String(32) | C380BEC2BFD727A4B6845133519F3AD6 | 签名值，详见签名算法 |
返回结果
业务系统处理后同步返回给支付中心，返回字符串 success 则表示成功，返回非success则表示处理失败，支付中心会再次通知业务系统。（通知频率为60/120/180/240/300,单位：秒）
注意：返回的字符串必须是小写，且前后不能有空格。
文档更新时间: 2021-10-25 12:06 作者：大森林
