文档名称
统一退款接口文档
业务模式
商户针对某一个已经成功支付的订单发起退款, 操作结果在同一会话中同步返回。
一、 退款方式
目前只支持原路返回退款
说明: 退到银行卡则是非实时的, 每个银行的处理速度不同, 一般发起退款后 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