---
url: "https://pay.weixin.qq.com/doc/v3/partner/4012082568.md"
title: "支付回调和查单实现指引"
doc_id: 4012082568
---

>更新时间：2024.12.18

## 1.背景

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

## 2.目标

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

## 3.方案概述

![](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/img/cfa2790c024eb52cd01fc338a9157856.png)

1. 商户App或者前端页面收到支付返回时，商户需要调用商户查单接口确认订单状态，并把查询结果展示给用户。

2. 商户后台需要准确、高效地处理微信支付发送的异步支付结果通知，并按接口规范把处理结果返回给微信支付。

3. 商户后台未收到异步支付结果通知时，商户应该主动调用《[微信支付查单接口](https://pay.weixin.qq.com/doc/v3/merchant/4012791858.md)》，同步订单状态。

4. 商户在T+1日从微信支付侧获取T日的交易账单，并与商户系统中的订单核对。如出现订单在微信支付侧成功，但是在商户侧未成功的情况，商户需要给用户补发货或者退款处理。


## 4.前端支付返回处理

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

- 前端返回“用户取消”的情况，则订单状态保持未支付状态，并提示用户支付未完成。

- 前端返回“成功”或“报错”的情况，商户需要调用商户查单接口，确认订单状态。

  - 如果商户查单接口明确返回支付成功，则给用户展示支付成功页。

  - 如果商户查单接口返回订单未支付，需要提醒用户“稍后进入订单管理页核实订单状态，不要重复发起支付”。商户后端需要及时获取、更新订单状态，实现逻辑参考[后端服务处理](https://pay.weixin.qq.com/doc/v3/partner/4012082568.md#5.%E5%90%8E%E7%AB%AF%E6%9C%8D%E5%8A%A1%E5%A4%84%E7%90%86)。当用户再次进入订单管理页面，对未支付的订单再次发起支付时，商户应该使用原单号发起，不要更换支付单号，避免用户重复支付。
- 前端调起支付和判断返回类型的方法请参考接口文档：

  - [JSAPI支付](https://pay.weixin.qq.com/doc/v3/merchant/4012791856.md)

  - [小程序支付](https://pay.weixin.qq.com/doc/v3/merchant/4012791897.md)

  - [App支付](https://pay.weixin.qq.com/doc/v3/merchant/4013070347.md)

### 4.2.H5支付

- 前端返回至发起支付的页面或者返回至指定的redirect\_url页面，需要在页面设置一个“已完成支付”的按钮让用户点击。


![](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/img/e660c05be8dadeda2c3e4f7df0460a6e.png)

"返回页面展示效果（仅供参考）"

- 用户点击“已完成支付”按钮，商户需要调用商户查单接口，确认订单状态。

  - 如果商户查单接口明确返回支付成功，则给用户展示支付成功页。

  - 如果商户查单接口返回订单未支付，需要提醒用户“稍后进入订单管理页核实订单状态，不要重复发起支付”。 商户后端需要及时获取、更新订单状态，实现逻辑参考【[后端服务处理](https://pay.weixin.qq.com/doc/v3/partner/4012082568.md#5.%E5%90%8E%E7%AB%AF%E6%9C%8D%E5%8A%A1%E5%A4%84%E7%90%86)】。当用户再次进入订单管理页面，对未支付的订单再次发起支付时，商户应该使用原单号发起，不要更换支付单号，避免用户重复支付。

### 4.3.NATIVE支付

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

![](https://gtimg.wechatpay.cn/resource/xres/mmpaydoc/static/img/74f8b1252f1dd601a6be7b4429b06dcc.png)

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

- 如果轮询商户查单接口返回支付成功，则给用户展示支付成功页。

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


## 5.后端服务处理

### 5.1.支付回调处理

商户后台需要准确、高效地处理微信支付发送的异步支付结果通知，并按接口规范把处理结果返回给微信支付。详情请参考[接口规范](https://pay.weixin.qq.com/doc/v3/merchant/4012081606.md)和[注意事项](https://pay.weixin.qq.com/doc/v3/merchant/4012075420.md)

### 5.2.定时轮询查单

如果长时间没有收到支付结果通知，商户后台应该定时轮询调用《[微信支付查单接口](https://pay.weixin.qq.com/doc/v3/merchant/4012791858.md)》去核实订单状态。

方案一：

以订单下单成功时间为基准（或者以前端支付返回成功或者报错后，第一次调用商户查单接口未成功的时间为基准），每隔5秒/30秒/1分钟/3分钟/5分钟/10分钟/30分钟调用《[微信支付查单接口](https://pay.weixin.qq.com/doc/v3/merchant/4012791858.md)》查询订单。（轮询时间间隔和次数，商户可以根据自身业务场景灵活设置）

方案二：

定时任务每隔30秒启动一次，找出最近10分钟内创建并且未支付的订单，调用《[微信支付查单接口](https://pay.weixin.qq.com/doc/v3/merchant/4012791858.md)》核实订单状态。系统记录订单查询的次数，在10次查询之后状态还是未支付成功，则停止后续查询，并调用《[关单接口](https://pay.weixin.qq.com/doc/v3/merchant/4012791860.md)》关闭订单。（轮询时间间隔和次数，商户可以根据自身业务场景灵活设置）

### 5.3.T+1日对账处理

5.3.1. 商户在T+1日上午10点以后，调用《[微信支付对账单下载接口](https://pay.weixin.qq.com/doc/v3/merchant/4012791866.md)》，或者登录微信商户平台手工下载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、如何判断微信支付查单接口返回的订单状态是支付成功？

商户收到《[微信支付查单接口](https://pay.weixin.qq.com/doc/v3/merchant/4012791858.md)》的响应报文，验证签名成功，并且返回的trade\_state为SUCCESS，则认为订单是支付成功。