# 微信支付 - 申请退款
该接口方法需要安装 小程序微信支付能力,如未安装需要前往安装才可以使用
# 接口英文名
wxpay_refund
注意:该接口仅支持在服务端调用
# 调用方式
# 1. 使用云函数在服务端调用申请退款接口
模板已内置了云函数代码,可以直接在微信开发者工具中下载到本地修改后使用。 也可以手动创建云函数来完成,点击在线代码示例,可以查看云函数示例代码。
- 下载模板云函数代码到本地
打开微信开发者工具界面,在cloudfunctions
目录点击右键,选择同步云函数列表
,同步模板中的云函数wxpayFunctions
到本地;然后在云函数wxpayFunctions
目录右键,选择下载
,即可下载模板内置的云函数代码到本地。如下图所示:
- 编辑下单云函数
修改云函数wxpayFunctions
下的wxpay_refund/index.js
代码,参数更新为业务实际参数。云函数编辑后,需要重新部署。
# 2. 小程序端调用云函数申请退款
小程序端调用云函数时,需要先在小程序端初始化云能力。修改app.js
,在 App
的 onLaunch
生命周期方法中添加云能力初始化代码,参数传入用户的云开发环境ID。
App({
onLaunch: function () {
wx.cloud.init({
// env 参数决定接下来小程序发起的云开发调用(wx.cloud.xxx)会默认请求到哪个云环境的资源
env: '{%TCB_ENV_ID%}',
// 是否在将用户访问记录到用户管理中,在控制台中可见,默认为false
traceUser: false,
});
},
});
小程序中调用步骤 1 中的云函数,查询订单。
// 小程序代码
wx.cloud.callFunction({
// 云函数名称
name: 'wxpayFunctions',
data: {
// 调用云函数中的申请退款方法
type: 'wxpay_refund',
// 业务其他参数...
},
success: (res) => {
console.log('申请退款结果: ', res);
},
});
# 3. 接收并处理退款通知(可选)
如果插件配置中配置了接收退款通知的回调函数
,则可以在自定义的云函数中接收到退款通知,通知中包含了订单详细支付信息,商户可自行处理并存储。
# 退款结果通知
模板wxpay
可配置接收退款通知的回调函数
,目前支持配置商户当前云开发环境下的一个或多个(以英文逗号,
分隔)云函数,模板会将支付通知消息下发给商户配置的云函数,商户可以在云函数中对消息进行处理。
注意 商户接收并处理消息时,如果微信收到应答不是成功或超时,则认为通知失败,会通过一定的策略定期重新发起通知,尽可能提高通知的成功率,但不保证通知最终能成功。
- 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。 推荐的做法是,当商户系统收到通知进行处理时,先检查对应业务数据的状态,并判断该通知是否已经处理。如果未处理,则再进行处理;如果已处理,则直接返回结果成功。
- 如果在所有通知频率后没有收到微信侧回调。商户应调用查询退款接口确认订单状态。
通知规则 如果微信收到商户的应答不符合规范或超时,则认为通知失败,会通过一定的策略定期重新发起通知,尽可能提高通知的成功率,但不保证通知最终能成功(通知频率为15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 总计 24h4m)
商户通知应答
- 返回的包体包含字段
code
值为SUCCESS
,标识商户接收消息通知成功;- 除成功包体外的其他响应格式,视为商户接收消息失败;
- 如果商户配置了多个接收消息通知的云函数,则所有函数都返回成功包体,才视为接收消息成功;否则,微信重试时会重复通知到所有的云函数。
# 更多说明
错误码请参考申请退款
# 入参:
参数 | 类型 | 必填 | 描述 |
---|---|---|---|
out_refund_no | string | 是 | 商户退款单号 |
transaction_id | string | 否 | 微信支付订单号,与out_trade_no二选一 |
out_trade_no | string | 否 | 商户订单号,与transaction_id二选一 |
reason | string | 否 | 退款原因 |
funds_account | string | 否 | 退款资金来源 |
amount | object | 是 | |
amount.refund | number | 否 | 退款金额 |
amount.total | number | 否 | 原订单金额 |
amount.currency | string | 否 | 退款币种 |
amount.from | array of object | 否 | |
amount.from[].account | string | 否 | 出资账户类型 |
amount.from[].amount | number | 否 | 出资金额 |
goods_detail | array of object | 否 | |
goods_detail[].merchant_goods_id | string | 否 | 商户侧商品编码 |
goods_detail[].wechatpay_goods_id | string | 否 | 微信支付商品编码 |
goods_detail[].goods_name | string | 否 | 商品名称 |
goods_detail[].unit_price | number | 否 | 商品单价 |
goods_detail[].refund_amount | number | 否 | 商品退款金额 |
goods_detail[].refund_quantity | number | 否 | 商品退货数量 |
# 出参:
参数 | 类型 | 描述 |
---|---|---|
requestID | string | 请求唯一ID |
result | object | |
result.code | number | 错误码 |
result.data | object | |
result.data.transaction_id | string | 微信支付交易订单号 |
result.data.amount | object | |
result.data.amount.payer_total | number | 现金支付金额,单位为分,只能为整数 |
result.data.amount.settlement_total | number | 应结订单金额=订单金额-免充值代金券金额,应结订单金额<=订单金额,单位为分 |
result.data.amount.total | number | 订单总金额,单位为分 |
result.data.amount.payer_refund | number | 退款给用户的金额,单位为分,不包含所有优惠券金额 |
result.data.amount.refund_fee | number | 手续费退款金额,单位为分 |
result.data.amount.discount_refund | number | 优惠退款金额<=退款金额,退款金额-代金券或立减优惠退款金额为现金,说明详见代金券或立减优惠,单位为分 |
result.data.amount.from | array of object | 退款出资的账户类型及金额信息 |
result.data.amount.from[].account | string | |
result.data.amount.from[].amount | number | |
result.data.amount.currency | string | 符合ISO 4217标准的三位字母代码,目前只支持人民币:CNY。 |
result.data.amount.settlement_refund | number | 去掉非充值代金券退款金额后的退款金额,单位为分,退款金额=申请退款金额-非充值代金券退款金额,退款金额<=申请退款金额 |
result.data.amount.refund | number | 退款标价金额,单位为分,可以做部分退款 |
result.data.out_trade_no | string | 原支付交易对应的商户订单号 |
result.data.promotion_detail | array of object | 优惠退款信息 |
result.data.promotion_detail[].promotion_id | string | |
result.data.promotion_detail[].scope | string | |
result.data.promotion_detail[].type | string | |
result.data.promotion_detail[].amount | number | |
result.data.promotion_detail[].refund_amount | number | |
result.data.promotion_detail[].goods_detail | array of object | |
result.data.promotion_detail[].goods_detail[].merchant_goods_id | string | |
result.data.promotion_detail[].goods_detail[].wechatpay_goods_id | string | |
result.data.promotion_detail[].goods_detail[].goods_name | string | |
result.data.promotion_detail[].goods_detail[].unit_price | number | |
result.data.promotion_detail[].goods_detail[].refund_amount | number | |
result.data.promotion_detail[].goods_detail[].refund_quantity | number | |
result.data.create_time | string | 退款受理时间,遵循rfc3339标准格式,格式为YYYY-MM-DDTHH:mm:ss+TIMEZONE,YYYY-MM-DD表示年月日,T出现在字符串中,表示time元素的开头,HH:mm:ss表示时分秒,TIMEZONE表示时区(+08:00表示东八区时间,领先UTC 8小时,即北京时间)。例如:2015-05-20T13:29:35+08:00表示,北京时间2015年5月20日13点29分35秒。 |
result.data.out_refund_no | string | 商户系统内部的退款单号,商户系统内部唯一,只能是数字、大小写字母_- |
result.data.funds_account | string | 退款所使用资金对应的资金账户类型。可选取值:UNSETTLED: 未结算资金,AVAILABLE: 可用余额,UNAVAILABLE: 不可用余额,OPERATION: 运营户,BASIC: 基本账户(含可用余额和不可用余额),ECNY_BASIC: 数字人民币基本账户 |
result.data.channel | string | 退款渠道。可选取值:ORIGINAL: 原路退款,BALANCE: 退回到余额,OTHER_BALANCE: 原账户异常退到其他余额账户,OTHER_BANKCARD: 原银行卡异常退到其他银行卡 |
result.data.success_time | string | 退款成功时间,退款状态status为SUCCESS(退款成功)时,返回该字段。 |
result.data.user_received_account | string | 取当前退款单的退款入账方,有以下几种情况:1)退回银行卡:{银行名称}{卡类型}{卡尾号} 2)退回支付用户零钱:支付用户零钱 3)退还商户:商户基本账户商户结算银行账户 4)退回支付用户零钱通:支付用户零钱通 |
result.data.refund_id | string | 微信支付退款号 |
result.data.status | string | 退款到银行发现用户的卡作废或者冻结了,导致原路退款银行卡失败,可前往商户平台(pay.weixin.qq.com)-交易中心,手动处理此笔退款。可选取值:SUCCESS: 退款成功,CLOSED: 退款关闭,PROCESSING: 退款处理中,ABNORMAL: 退款异常 |