112 lines
8.2 KiB
Markdown
112 lines
8.2 KiB
Markdown
接口应在服务端调用，不可在前端（小程序、网页、APP等）直接调用。具体可参考[接口接入指南](https://www.yuque.com/shunchenghuichuang/iasgxw/lw3ftk64nq0f2gsg)。
|
||
|
||
接口英文名：OrderRefund
|
||
|
||
该接口用于对支付成功的订单进行退款。支持全额退款和部分退款。
|
||
|
||
## 1、调用方式
|
||
### HTTPS调用
|
||
`POST /api/app/refundOrder/orderRefund`
|
||
|
||
## 2、请求参数
|
||
### <font style="color:rgb(34, 34, 34);">请求体 </font>`<font style="color:rgb(34, 34, 34);">Request Payload</font>`
|
||
| 参数名 | 类型 | 必填 | 字段长度 | 说明 |
|
||
| :--- | :--- | :--- | :--- | :--- |
|
||
| service | string | 是 | - | 接口名称。<br/><font style="color:rgb(232,50,60);">此处固定值为：</font>unified_refund |
|
||
| sign_type | string | 否 | 10 | 接口签名类型，枚举如下：<br/>MD5：MD5签名算法<br/>SM3：国密SM3签名算法 不传默认使用MD5算法 |
|
||
| merchant_id | string | 是 | 10 | 财务交易中心商户号 |
|
||
| schc_order_id | string | 否 | 16 | 财务交易中心订单号。<br/><font style="color:rgb(232,50,60);">schc</font><font style="color:rgb(232,50,60);">_order_id</font><font style="color:rgb(232,50,60);">和</font><font style="color:rgb(232,50,60);">third_order_id</font><font style="color:rgb(232,50,60);">两者必填其一，都填优先使用</font><font style="color:rgb(232,50,60);">schc</font><font style="color:rgb(232,50,60);">_order_id</font><font style="color:rgb(232,50,60);">。</font><br/><font style="color:rgb(232,50,60);">如商户/服务商需要退3个月以上的交易，必须使用schc_order_id发起退款</font> |
|
||
| third_order_id | string | 否 | 64 | 商户订单号。<br/><font style="color:rgb(232,50,60);">schc_order_id和third_order_id两者必填其一，都填优先使用schc_order_id。</font> |
|
||
| merchant_refund_id | string | 是 | 64 | 商户退款订单号。<br/>由商户/服务商生成，支持数字字母格式，不能包括“_”等特殊字符，需要确认在商户下唯一。 |
|
||
| refund_amount | string | 是 | 10 | 退款金额，单位：分。<br/>可进行部分退款，不可超退。 |
|
||
| refund_type | string | 否 | 1 | 退款出资类型。<br/>0：当日正向交易抵扣退款<br/>1：可用商户账户余额退款（优先使用正向交易抵扣，正向交易不够抵扣情况下可用账户余额进行退款）<br/>2：只可用商户账户余额退款。<br/><font style="color:rgb(232,50,60);">特别说明：</font><font style="color:rgb(232,50,60);">1.</font><font style="color:rgb(232,50,60);"> </font><font style="color:rgb(232,50,60);">原交易订单为跑批清分时，该参数默认为</font><font style="color:rgb(232,50,60);">1</font><font style="color:rgb(232,50,60);">，传值则按传值对应模式校验能否退款。</font><br/><font style="color:rgb(232,50,60);">原交易订单为实时清分时，无论传几均默认按2处理，即从商户账户余额退款</font> |
|
||
| nonce_str | string | 是 | 32 | 随机字符串 |
|
||
| sign | string | 是 | 32 | 签名 |
|
||
| req_serial_no | string | 是 | 32 | 本次交易的请求流水号 |
|
||
| notify_url | string | 否 | 128 | 交易通知地址。<br/>接收财务交易中心通知的URL，需做UrlEncode 处理，需要绝对路径，确保顺成能正确访问，若不需要回调请忽略 |
|
||
| shop_no | string | 否 | 16 | 商户门店编号。<br/>只能是汉字、英文字母、数字 |
|
||
| attach | string | 否 | 96 | 附加数据。支付成功原样返回。<br/>注意：只能是汉字、英文字母、数字 |
|
||
|
||
|
||
## 3、返回参数
|
||
### <font style="color:rgb(34, 34, 34);">返回体 </font>`<font style="color:rgb(34, 34, 34);">Response Payload</font>`
|
||
XML格式返回
|
||
|
||
| 参数名 | 类型 | 说明 |
|
||
| :--- | :--- | --- |
|
||
| resp_code | string | 通信状态码。<br/>200 - 成功。<br/>非200 - 失败。<br/>注：此字段是通信标识，业务状态要看result_code |
|
||
| resp_msg | string | 通信错误说明<br/>resp_code非200时返回 |
|
||
| cost_time | string | 请求耗时。<br/>请求接口耗费的时间，单位毫秒 |
|
||
| req_serial_no | string | 本次交易的请求流水号，原样返回 |
|
||
| <font style="color:rgb(232,50,60);">以下参数在resp_code=200时返回</font> | | |
|
||
| result_code | string | 业务状态码。<br/>0 - 退款受理成功<br/>非0 - 退款受理失败<br/><font style="color:rgb(232,50,60);">注：退款受理成功不代表退款成功，具体请结合该笔订单的状态status来确定退款结果</font> |
|
||
| error_code | string | 退款失败错误码。<br/>退款失败时返回<br/>错误码 |
|
||
| error_msg | string | 退款失败原因。<br/>退款失败时返回具体失败原因说明 |
|
||
| nonce_str | string | 随机字符串 |
|
||
| sign | string | 签名 |
|
||
| sign_type | string | 签名类型，枚举如下：<br/>MD5：MD5签名算法<br/>SM3：国密SM3签名算法 返回接口请求时设定的签名类型进行签名。 |
|
||
| merchant_id | string | 财务交易中心商户号 |
|
||
| third_order_id | string | 商户订单号。<br/>商户原支付交易订单号 |
|
||
| sub_merchant_id | string | 通道商户号。<br/>该笔订单交易时所使用的上游商户号，即微信商户号、或者支付宝商户号、或者银联商户号等 |
|
||
| <font style="color:rgb(232,50,60);">以下参数在result_code=0时返回</font> | | |
|
||
| schc_order_id | string | 顺成交易订单号。<br/>该笔退款交易对应的原支付交易订单号。 |
|
||
| status | string | 订单支付状态，枚举如下：<br/>10：退款中<br/>11：退款成功<br/>12：退款失败 |
|
||
| refund_amount | string | 退款金额，单位：分 |
|
||
| buyer_refund_amount | string | 买家实际退款金额，单位：分 |
|
||
| merchant_refund_id | string | 商户退款订单号。 |
|
||
| schc_refund_id | string | 交易中心退款订单号。<br/>退款受理成功后，会返回该笔退款对应的交易中心退款交易订单号。 |
|
||
| amount | string | 订单总金额。单位：分。<br/><font style="color:rgb(245,34,45);">退款情况下，amount和total_amount数值一样。</font> |
|
||
| total_amount | | 订单总金额。单位：分。<br/><font style="color:rgb(245,34,45);">退款情况下，amount和total_amount数值一样。</font> |
|
||
| order_balance | string | 订单剩余可退金额。单位：分。<br/>本次退款后，订单剩余可继续发起退款的金额 |
|
||
| attach | string | 退款附加数据。<br/>原样返回退款请求时上送的attach内容。如果请求时没有上送attach参数，则不返回。<br/>注意：只能是汉字、英文字母、数字 |
|
||
|
||
|
||
## 4、注意事项
|
||
|
||
|
||
## 5、代码示例
|
||
请求参数：
|
||
|
||
```json
|
||
{
|
||
"service": "unified_refund",
|
||
"sign_type": "MD5",
|
||
"merchant_id": "123456789",
|
||
"schc_order_id": "0000273593826042",
|
||
"third_order_id": "17707745873403A1F3E866823",
|
||
"merchant_refund_id": "17708871997883A1F3E866823",
|
||
"refund_amount": "1",
|
||
"nonce_str": "17707745873403A1F3E866823",
|
||
"sign": "YWU5NDgyNzIwZTc3MTRkZGU4YTY2OTQ2MzE0N2VmMjY=",
|
||
"req_serial_no": "17707745873403A1F3E866823"
|
||
}
|
||
```
|
||
|
||
<font style="color:rgb(52, 64, 84);"></font>
|
||
|
||
<font style="color:rgb(52, 64, 84);">返回参数：</font>
|
||
|
||
```html
|
||
<schc>
|
||
<resp_code><![CDATA[200]]></resp_code>
|
||
<sign><![CDATA[09C77101ECF7040747B0430011E8F197]]></sign>
|
||
<result_code><![CDATA[0]]></result_code>
|
||
<refund_time><![CDATA[2022-09-30 15:14:15]]></refund_time>
|
||
<third_order_id><![CDATA[20220924114903108]]></third_order_id>
|
||
<nonce_str><![CDATA[yvzpkpyhsmpxcftbirmpmuzkibkbxmyt]]></nonce_str>
|
||
<schc_refund_id><![CDATA[0000601181922273]]></schc_refund_id>
|
||
<order_balance><![CDATA[0]]></order_balance>
|
||
<merchant_id><![CDATA[0000000018]]></merchant_id>
|
||
<status><![CDATA[10]]></status>
|
||
<cost_time><![CDATA[1508]]></cost_time>
|
||
<sign_type><![CDATA[MD5]]></sign_type>
|
||
<amount><![CDATA[1]]></amount>
|
||
<refund_amount><![CDATA[1]]></refund_amount>
|
||
<sub_merchant_id><![CDATA[2088410502098221]]></sub_merchant_id>
|
||
<total_amount><![CDATA[1]]></total_amount>
|
||
<schc_order_id><![CDATA[0000700081922267]]></schc_order_id>
|
||
<merchant_refund_id><![CDATA[T20220930151413M167JoEe]]></merchant_refund_id>
|
||
<req_serial_no><![CDATA[17707745873403A1F3E866823]]></req_serial_no>
|
||
</schc>
|
||
```
|