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