接口说明
接口名称 | order_refund |
---|---|
是否幂等 | 是 |
接口模式 | 直连 |
异步通知 | 是 |
应用场景
商户侧需要针对原支付订单退款时,可通过该接口发起。
注意事项
- 同一笔支付订单支持多次退款,多次退款需要传递相同的原支付单商户订单号和不同的退款订单号,多次申请退款总金额不能超过原支付订单总金额。
- 针对同一笔支付订单不支持申请退款接口和确认分账接口同时发起。
- 针对同一笔支付订单需要多次部分退款时,建议不同批次退款,不支持并发退款。
- 交易时间超过一年的订单无法发起退款。
- 申请退款接口同步返回结果仅表示业务受理结果,当resultCode返回SUCCESS,状态为REFUND表示退款申请成功,退款结果通过请求商户侧服务端通知地址告知,或商户发起退款查询退款结果。
- 普通订单、分账订单退款时,请依照该计算公式:退款总金额 = 退款金额 + 营销退款金额 = 分账明细退款金额 + 剩余未分账金额 + 垫资金额。
- 支付下单送入分账信息时,到达分账时间前产生退款,则分账订单会被取消。
- 分账退款信息参数涉及确认分账接口进行的分账商户,在发起退款时,请确认分账订单是否为分账成功,否则会退款失败。
接口参数
- 请求:
字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|---|
代理商商户号 | agentMerId | 否 | S(16) | 100000 | 宝付支付分配的商户号 |
代理商终端号 | agentTerId | 否 | S(16) | 100000 | 宝付支付分配的终端号 |
商户号 | merId | 是 | S(16) | 100000 | 宝付支付分配的商户号 |
终端号 | terId | 是 | S(16) | 100000 | 宝付支付分配的终端号 |
商户名称 | merchantName | 否 | S(128) | 商户名称 | 商户名称 |
原支付订单宝付交易号 | originTradeNo | 否 | S(32) | 12312312312 | 原支付订单宝付交易号,推荐传入此值 |
原支付订单商户订单号 | originOutTradeNo | 否 | S(32) | 20210315155012 | 原支付订单商户订单号,与原支付订单宝付交易号二选一比传 |
退款订单号 | outTradeNo | 是 | S(50) | 20210315155013 | 商户系统内部退款订单号,同一个商户号下唯一 |
服务端通知地址 | notifyUrl | 否 | S(128) | https://www.example.com/return_url | 退款处理完成后请求商户侧服务端地址 |
退款金额 | refundAmt | 是 | I | 100 | 单位:分,退款金额不得大于用户实际付款金额 |
退款总金额 | totalAmt | 是 | I | 200 | 如包含营销信息,则退款总金额=退款金额+营销退款总金额,反之退款总金额=退款金额 |
交易时间 | txnTime | 是 | T | 20210315155012 | 订单交易时间 |
附加字段 | attach | 否 | S(128) | 预留字段 | |
请求方保留域 | reqReserved | 否 | S(128) | 预留字段 | |
分账退款信息 | sharingRefundInfo | 否 | C | [{“sharingAmt”:100,”sharingMerId”:”100000”},{“sharingAmt”:200,”sharingMerId”:”100001”}] | JSON数组 |
-商户号 | sharingMerId | 是 | S(16) | 100000 | 宝付支付分配的商户号 |
-分账金额 | sharingAmt | 是 | I | 100 | 分账金额,单位:分,如1元则传入100 |
营销退款信息 | mktRefundInfo | 否 | C | {“mktAmt”:100,”mktMerId”:”100000”} | JSON格式,目前仅支持交易商户承担营销金额 |
-商户号 | mktMerId | 是 | S(16) | 100000 | 宝付支付分配的商户号 |
-营销金额 | mktAmt | 是 | I | 100 | 营销金额,单位:分,如:1元则传入100 |
垫资金额 | advanceAmt | 否 | I | 100 | 如果需要垫资传入 |
退款原因 | refundReason | 是 | s(128) |
- 返回
字段名 | 变量名 | 必填 | 类型 | 示例值 | 描述 |
---|---|---|---|---|---|
原支付订单宝付交易号 | originTradeNo | 否 | S(32) | 12312312312 | 与商户订单号对应的宝付侧唯一订单号,推荐传入此值 |
原支付订单商户订单号 | originOutTradeNo | 否 | S(32) | 20210315155012 | 商户系统内部订单号,同一个商户号下唯一 |
商户退款订单号 | outTradeNo | 是 | S(32) | 20210315155013 | 商户系统内部退款订单号,同一个商户号下唯一 |
宝付退款交易号 | tradeNo | 是 | S(32) | 12312312312 | 与商户退款订单号对应的宝付侧唯一退款订单号, |
退款金额 | refundAmt | 是 | I | 100 | 单位:分,退款金额不得大于用户实际付款金额 |
退款总金额 | totalAmt | 是 | I | 200 | 如包含营销信息,则退款总金额=退款金额+营销退款总金额,反之退款总金额=退款金额 |
业务结果 | resultCode | 是 | S(16) | SUCCESS | SUCCESS:业务受理成功,FAIL:业务受理失败 |
订单状态 | refundState | 否 | E | REFUND | 详见附录订单状态 |
错误代码 | errCode | 否 | S(32) | 当业务结果FAIL时,返回错误代码 | |
错误描述 | errMsg | 否 | S(128) | 当业务结果为FAIL时,返回错误描述 | |
请求方保留域 | reqReserved | 否 | S(128) | 预留字段 |
作者:xiaofeng 创建时间:2025-03-25 15:24
最后编辑:xiaofeng 更新时间:2025-06-05 10:43
最后编辑:xiaofeng 更新时间:2025-06-05 10:43