文档名称

统一退款接口文档

业务模式

商户针对某一个已经成功支付的订单发起退款, 操作结果在同一会话中同步返回。
一、 退款方式
目前只支持原路返回退款
说明: 退到银行卡则是非实时的, 每个银行的处理速度不同, 一般发起退款后 1-3 个工作日内到账。
同一笔单的部分退款需要设置相同的订单号和不同的 out_refund_no,一笔退款失败后重新提交,要采用原来的out_refund_no。总退款金额不能超过用户实际支付金额(现金券金额不能退款)
二、 退款限制
商户在退款操作时应该注意退款限制, 避免发起不会成功的退款请求, 下面是主要的退款限制:
1.在系统中, 只要退款累计金额不超过交易单支付总额, 一笔交易单可以多次退款, 退款申请单号( 退款接口中有此参数) 唯一确定一次退款, 而不是交易单号确定一次退款。 退款申请单号由商户生成, 所以商户一定要保证退款申请单的唯一性。 商家在退款过程中要特别注意, 只有在能确定退款失败的情况下, 才能重新发起另一笔退款。
2.目前大多数银行都支持全额退款和部分退款, 但是也有少数银行不支持全额退款或部分退款, 或者不支持退款。 在这种情况下, 商户可以与买家协调, 退到微信余额账户中。
目前只提供无钥退款接口, 需要有钥退款接口的商户, 请联系商务说明。

交互模式

后台系统调用交互模式

请求参数列表

请求url: https://pay.xrtpay.cn/xrtpay/gateway

POST XML 内容体进行请求

字段名 变量名 必填 类型 说明
接口类型 service String(32) unified.trade.refund
版本号 version String(8) 默认值是 2.0。
字符集 charset String(8) 可选值 UTF-8,默认为 UTF-8。
签名方式 sign_type String(8) 取值MD5或者sm3 默认: MD5
商户号 mch_id String(32) 商户号, 由技术部分配
商户订单号 out_trade_no String(32) 商户系统内部的订单号 , out_trade_no和transaction_id 至少一个必 填 ,同 时存 在 时transaction_id 优先
平台订单号 transaction_id String(32) 平台订单号, out_trade_no 和 transaction_id 至少一个必填, 同时存在时 transaction_id 优先
商户退款单号 out_refund_no String(32) 商户退款单号, 32 个字符内、 可包含字母,确保在商户系统唯一。 同个退款单号多次请求, 公司当一个单处理, 只会退一次款。 如果出现退款不成功, 请采用原退款单号重新发起, 避免出现重复退款。
总金额 total_fee Int 订单总金额, 单位为分
退款金额 refund_fee Int 退款总金额,单位为分,可以做部分退款
操作员 op_user_id String(32) 操作员帐号,默认为商户号
交易时间 trade_date string(8) 交易时间,为空则查当天或者昨天
退款渠道 refund_channel String(16) ORIGINAL-原路退款, 默认BALANCE-余额
随机字符串 nonce_str String(32) 随机字符串, 不长于 32 位
签名 sign String(32) MD5 签名结果, 详见“ 数字签名 MD5 签名规则”

返回结果

数据按 XML 的格式实时返回

字段名 变量名 必填 类型 说明
版本号 version String(8) 版本号, version 默认值是 2.0
字符集 charset String(8) 可选值 UTF-8 , 默认为 UTF-8。
签名方式 sign_type String(8) 签名类型, 取值: MD5 默认: MD5
返回状态码 status String(16) 0 表示成功非 0 表示失败此字段是通信标识,非交易标识,交易是否成功需要查看 result_code 来判断
返回信息 message String(128) 返回信息, 如非空, 为错误原因签名失败参数格式校验错误
以下字段在status 和 result_code 都为 0 的时候有返回
业务结果 result_code String(16) 0 表示成功非 0 表示失败
商户号 mch_id String(32) 商户号, 由技术部分配
设备号 device_info String(32) 终端设备号
随机字符串 nonce_str String(32) 随机字符串, 不长于 32 位
错误代码 err_code String(32) 具体错误码请看文档最后错误码列表
签名 sign String(32) MD5 签名结果, 详见“ 数字签名 MD5 签名规则”
以下字段在status 和 result_code 都为 0 的时候有返回
平台订单号 transaction_id String(32) 平台订单号。
商户订单号 out_trade_no String(32) 商户系统内部的订单号
商户退款单号 out_refund_no String(32) 商户退款单号
平台退款单号 refund_id String(32) 平台退款单号
退款渠道 refund_channel String(16) ORIGINAL—原路退款,默认BALANCE—退回到余额
退款金额 refund_fee Int 退款总金额,单位为分,可以做部分退款
退款结算金额 settlement_refund_fee int 退款结算金额
文档更新时间: 2022-03-03 16:42   作者:EricYang