支付回调和查单实现指引

更新时间:2023.07.25

# 1.背景

由于网络异常或者系统的波动,可能会导致用户支付成功,但是商户侧未能成功接收到支付结果通知,进而显示订单未支付的情况。商户侧的订单状态更新不及时,容易造成用户投诉,甚至是重复支付的情况发生。

# 2.目标

商户在未能收到支付结果通知时,也能及时、准确地获取到订单的支付状态,提升商户系统的健壮性,减少因为订单状态不同步导致的用户投诉。

# 3.方案概述

图片
  1. 商户App或者前端页面收到支付返回时,商户需要调用商户查单接口确认订单状态,并把查询结果展示给用户。
  2. 商户后台需要准确、高效地处理微信支付发送的异步支付结果通知,并按接口规范把处理结果返回给微信支付。
  3. 商户后台未收到异步支付结果通知时,商户应该主动调用《微信支付查单接口》,同步订单状态。
  4. 商户在T+1日从微信支付侧获取T日的交易账单,并与商户系统中的订单核对。如出现订单在微信支付侧成功,但是在商户侧未成功的情况,商户需要给用户补发货或者退款处理。

# 4.前端支付返回处理

# 4.1.公众号、小程序、App支付

  • 前端返回“用户取消”的情况,则订单状态保持未支付状态,并提示用户支付未完成。
  • 前端返回“成功”或“报错”的情况,商户需要调用商户查单接口,确认订单状态。
    • 如果商户查单接口明确返回支付成功,则给用户展示支付成功页。
    • 如果商户查单接口返回订单未支付,需要提醒用户“稍后进入订单管理页核实订单状态,不要重复发起支付”。商户后端需要及时获取、更新订单状态,实现逻辑参考后端服务处理 (opens new window)。当用户再次进入订单管理页面,对未支付的订单再次发起支付时,商户应该使用原单号发起,不要更换支付单号,避免用户重复支付。
  • 前端调起支付和判断返回类型的方法请参考接口文档:

# 4.2.H5支付

  • 前端返回至发起支付的页面或者返回至指定的redirect_url页面,需要在页面设置一个“已完成支付”的按钮让用户点击。
图片

"返回页面展示效果(仅供参考)"

  • 用户点击“已完成支付”按钮,商户需要调用商户查单接口,确认订单状态。
    • 如果商户查单接口明确返回支付成功,则给用户展示支付成功页。
    • 如果商户查单接口返回订单未支付,需要提醒用户“稍后进入订单管理页核实订单状态,不要重复发起支付”。 商户后端需要及时获取、更新订单状态,实现逻辑参考【后端服务处理 (opens new window)】。当用户再次进入订单管理页面,对未支付的订单再次发起支付时,商户应该使用原单号发起,不要更换支付单号,避免用户重复支付。

# 4.3.NATIVE支付

前端显示支付二维码之后,前端定时轮询调用商户查单接口确认订单的状态。

图片
页面展示效果(仅供参考)

比如间隔2秒查询一次,一直轮询60秒。(轮询时间间隔和次数,商户可以根据自身业务场景灵活设置)

  • 如果轮询商户查单接口返回支付成功,则给用户展示支付成功页。
  • 如果超过系统设置的时间,商户查单接口仍未返回支付成功,则退出轮询,提醒用户交易超时。

# 5.后端服务处理

# 5.1.支付回调处理

商户后台需要准确、高效地处理微信支付发送的异步支付结果通知,并按接口规范把处理结果返回给微信支付。详情请参考接口规范注意事项

# 5.2.定时轮询查单

如果长时间没有收到支付结果通知,商户后台应该定时轮询调用《微信支付查单接口》去核实订单状态。

方案一

以订单下单成功时间为基准(或者以前端支付返回成功或者报错后,第一次调用商户查单接口未成功的时间为基准),每隔5秒/30秒/1分钟/3分钟/5分钟/10分钟/30分钟调用《[微信支付查单接口](/merchant-articles/apis/jsapi-payment/query-by-wx-trade-no.md查询一次,最后一次查询还是未返回支付成功状态,则停止后续查询,并调用《关单接口 (opens new window)》关闭订单。(轮询时间间隔和次数,商户可以根据自身业务场景灵活设置)

方案二

定时任务每隔30秒启动一次,找出最近10分钟内创建并且未支付的订单,调用《微信支付查单接口》核实订单状态。系统记录订单查询的次数,在10次查询之后状态还是未支付成功,则停止后续查询,并调用《关单接口 (opens new window)》关闭订单。(轮询时间间隔和次数,商户可以根据自身业务场景灵活设置)

# 5.3.T+1日对账处理

5.3.1. 商户在T+1日上午10点以后,调用《微信支付对账单下载接口 (opens new window)》,或者登录微信商户平台手工下载T日交易账单,然后根据对账单中的订单数据,逐笔与商户系统中的订单核对。

5.3.2. 核对时有如下几种情况:

  • 订单匹配成功,并且状态都是支付成功:正常情况,对账成功。
  • 订单匹配成功,但是商户侧状态非支付成功:商户根据自身业务情况,决定是否把订单状态更新为支付成功并给用户发货,或者是给用户发起退款。
  • 订单匹配失败,对账单中的单号在商户系统未找到记录:异常情况,需要商户排查系统是否出现数据异常。
  • 订单匹配失败,商户系统中成功的订单在对账单中未找到记录:异常情况,需要商户排查是否订单处理逻辑有bug。

# 6.常见问题

# 1、前端返回如何区分是成功返回,还是用户取消支付或者异常?

公众号支付,通过JSAPI返回的res.err_msg值判断:

描述 解决方案
get_brand_wcpay_request:ok 支付成功
get_brand_wcpay_request:cancel 支付过程中用户取消
get_brand_wcpay_request:fail 支付失败

小程序支付,通过回调类型判断:

回调类型 errMsg 说明
success requestPayment:ok 调用支付成功
fail requestPayment:fail cancel 用户取消支付
fail requestPayment:fail (detail message) 调用支付失败,其中 detail message 为后台返回的详细失败原因

App支付,通过onResp函数返回的errCode值判断:

名称 描述 解决方案
0 成功 展示页面成功
-1 错误 可能的原因:签名错误、未注册AppID、项目设置AppID不正确、注册的AppID与设置的不匹配、其他异常原因等
-2 用户取消 无需处理。发生场景:用户不支付了,点击取消,返回App

# 2、如何判断微信支付查单接口返回的订单状态是支付成功?

商户收到《微信支付查单接口》的响应报文,验证签名成功,并且返回的return_coderesult_codetrade_state这3个参数值同时为SUCCESS,则认为订单是支付成功;调用查单接口遇到网络超时,未收到返回,或者返回的return_coderesult_code不同时为SUCCESS,则代表订单状态不明确,需要再次调用查单接口确认。