开发指引

更新时间：2024.11.21

1. 接口规则

为了在保证支付安全的前提下，带给商户简单、一致且易用的开发体验，我们推出了全新的微信支付APIv3接口。该版本API的具体规则请参考APIv3接口规则。

2. 开发准备

2.1. 搭建和配置开发环境

开发者应当依据自身的编程语言来构建并配置相应的开发环境。

2.2. 业务开发配置

2.2.1. 开通H5支付权限

前往微信支付商户平台—>产品中心—>H5支付—>申请开通。

2.2.2.服务器配置要求

注意

域名必须通过ICP备案
域名填写格式不包含"HTTP://"或"HTTPS://"

3. 快速接入

3.1. 业务流程图

安全标准规范流程图

重点步骤说明：

步骤1 用户向商户系统后台请求下单，商户后台必须做好安全校验。

当跨域请求不是简单请求时，浏览器会发起Options预检请求，此时商户后台需要支持Options请求且校验Origin头部，如果不在允许的白名单列表内，则返回403且不返回"Access-Control-Allow-*"相关头部。
针对GET/POST的跨域下单请求，商户后台需要校验Origin头部是否合法且用户Cookie是否完备（若用户未登陆则先引导登陆商户站点），否则返回403且不返回"Access-Control-Allow-*"相关头部。

步骤2 商户可通过H5下单API创建支付订单。

步骤3 用户通过微信外部的浏览器调起微信支付中间页，进行发起支付请求。

步骤5 用户支付成功后，商户可接收到微信支付支付结果通知支付通知API。

步骤8 商户在没有接收到微信支付结果通知的情况下需要主动调用商户订单号查询订单查询支付结果。

注意

商户需按照安全规范进行接入，若因未遵循规范接入而出现安全问题，财付通将根据《微信支付服务协议》条款处理。
以上图示，仅为示例，只供参考。请商户自行确认是否实现了跨域访问白名单限制和用户登录态校验。

3.2. API接入（含示例代码）

文档展示了如何使用微信支付服务端 SDK 快速接入支付有礼，完成与微信支付对接的部分。

注意

文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。
以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。

3.2.1. 【服务端】H5下单

步骤说明：用户使用微信外部的浏览器访问商户H5页面，当用户选择相关商品购买时，商户系统先调用该接口在微信支付服务后台生成预支付交易单。

JAVA示例代码：

1public void CreateOrder() throws Exception{
2//请求URL
3HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/pay/transactions/h5");
4          
5// 请求body参数
6String reqdata = "{"
7              + "\"amount\": {"
8              + "\"total\": 100,"
9              + "\"currency\": \"CNY\""
10              + "},"
11              + "\"scene_info\": {"
12              + "\"payer_client_ip\":\"14.23.150.211\","
13              + "\"h5_info\": {"
14              + "\"type\": \"IOS\"" + "}},"
15              + "\"mchid\": \"1900006891\","
16              + "\"description\": \"Image形象店-深圳腾大-QQ公仔\","
17              + "\"notify_url\": \"https://www.weixin.qq.com/wxpay/pay.php\","
18              + "\"out_trade_no\": \"1217752501201407033233388881\","
19              + "\"goods_tag\": \"WXG\","
20              + "\"appid\": \"wxdace645e0bc2c424\"" + "}";     
21StringEntity entity = new StringEntity(reqdata,"utf-8");
22entity.setContentType("application/json");
23httpPost.setEntity(entity);
24httpPost.setHeader("Accept", "application/json");
25//完成签名并执行请求
26CloseableHttpResponse response = httpClient.execute(httpPost);
27try {
28    int statusCode = response.getStatusLine().getStatusCode();
29    if (statusCode == 200) {
30        System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
31    } else if (statusCode == 204) {
32        System.out.println("success");
33    } else {
34        System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
35        throw new IOException("request failed");
36    }
37} finally {
38    response.close();
39}
40}

PHP示例代码：

1try {
2$resp = $client->request(
3    'POST',
4    'https://api.mch.weixin.qq.com/v3/pay/transactions/h5', //请求URL
5    [
6        // JSON请求体
7        'json' => [
8            "time_expire" => "2018-06-08T10:34:56+08:00",
9            "amount" => [
10                "total" => 100,
11                "currency" => "CNY",
12            ],
13            "mchid" => "1900006891",
14            "description" => "Image形象店-深圳腾大-QQ公仔",
15            "notify_url" => "https://www.weixin.qq.com/wxpay/pay.php",
16            "out_trade_no" => "1217752501201407033233368022",
17            "goods_tag" => "WXG",
18            "appid" => "wxdace645e0bc2c424",
19            "attach" => "自定义数据说明",
20            "scene_info" => [
21                "store_info" => [
22                    "address" => "广东省深圳市南山区科技中一道10000号",
23                    "area_code" => "440305",
24                    "name" => "腾讯大厦分店",
25                    "id" => "0001",
26                ],
27                "device_id" => "013467007045764",
28                "payer_client_ip" => "14.23.150.211",
29                "h5_info"=>[
30                    "type"=>"IOS"
31                ],
32            ]
33        ],
34        'headers' => [ 'Accept' => 'application/json' ]
35    ]
36);
37$statusCode = $resp->getStatusCode();
38if ($statusCode == 200) { //处理成功
39    echo "success,return body = " . $resp->getBody()->getContents()."\n";
40} else if ($statusCode == 204) { //处理成功，无返回Body
41    echo "success";
42}
43} catch (RequestException $e) {
44// 进行错误处理
45echo $e->getMessage()."\n";
46if ($e->hasResponse()) {
47    echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
48}
49return;
50}

重要入参说明：

out_trade_no：商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一。
description：商品描述。
notify_url：支付回调通知URL，该地址必须为直接可访问的URL，不允许携带查询串。
total：订单总金额，单位为分。
scene_info：支付场景描述。

更多参数、响应详情及错误码请参见H5下单接口文档。

3.2.2. 【客户端】微信外部的浏览器拉起微信支付中间页

步骤说明：通过H5下单API成功获取H5下单返回的支付中间页（h5_url）后，用户需要通过微信外部的浏览器调起微信支付收银台

注意

h5_url为拉起微信支付收银台的中间页面，可通过访问该URL来拉起微信客户端，完成支付，h5_url的有效期为5分钟。
微信支付收银台中间页会进行H5权限的校验，安全性检查。
正常流程用户支付完成后会返回至发起支付的页面，如需返回至指定页面，则可以在h5_url后拼接上"redirect_url"参数，来指定回调页面。您希望用户支付完成后跳转至https://www.wechatpay.com.cn，则拼接后的地址为h5_url= https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx20161110163838f231619da20804912345&package=1037687096&redirect_url=https%3A%2F%2Fwww.wechatpay.com.cn。
需对redirect_url进行urlencode处理。
由于设置redirect_url后,回跳指定页面的操作可能发生在：
- 微信支付中间页调起微信收银台后超过5秒。
- 用户点击“取消支付”或支付完成后点击“完成”按钮。因此无法保证页面回跳时，支付流程已结束，所以商户设置的redirect_url地址不能自动执行查单操作，应让用户去点击按钮触发查单操作，回跳页面展示效果可参考下图。

3.2.3. 【服务端】接收支付结果通知

步骤说明：当用户完成支付，微信会把相关支付结果将通过异步回调的方式通知商户，商户需要接收处理，并按文档规范返回应答。

注意

支付结果通知是以POST 方法访问商户设置的通知URL，通知的数据以JSON 格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情。
加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名，并将签名值放在通知的HTTP头"Wechatpay-Signature"。商户应当验证签名，以确认请求来自微信，而不是其他的第三方。签名验证的算法请参考《微信支付API v3签名验证》。
支付通知HTTP应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx。
商户成功接收到回调通知后应返回成功的HTTP应答码为200或204。
同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
对后台通知交互时，如果微信收到商户的应答不符合规范或超时，微信认为通知失败，微信会通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但微信不保证通知最终能成功。（通知频率为15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 总计 24h4m）。

特别提醒：商户系统对于开启结果通知的内容一定要做签名验证，并校验通知的信息是否与商户侧的信息一致，防止数据泄露导致出现“假通知”，造成资金损失。

更多参数、响应详情及错误码请参见支付结果通知接口文档。

3.2.4. 【服务端】查询订单

步骤说明：当商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知时，商户可通过查询订单接口核实订单支付状态。

注意

查询订单可通过微信支付订单号和商户订单号两种方式查询，两种查询方式返回结果相同。

需要调用查询接口的情况：

当商户后台、网络、服务器等出现异常，商户系统最终未接收到支付通知。
调用支付接口后，返回系统错误或未知交易状态情况。
调用付款码支付API，返回USERPAYING的状态。
调用关单或撤销接口API之前，需确认支付状态。

JAVA示例代码：

1public void QueryOrder() throws Exception {
2   
3    //请求URL
4    URIBuilder uriBuilder = new URIBuilder("https://api.mch.weixin.qq.com/v3/pay/transactions/id/4200000745202011093730578574");
5    uriBuilder.setParameter("mchid", mchId);
6    
7    //完成签名并执行请求
8    HttpGet httpGet = new HttpGet(uriBuilder.build());
9    httpGet.addHeader("Accept", "application/json");
10    CloseableHttpResponse response = httpClient.execute(httpGet);
11    
12    try {
13        int statusCode = response.getStatusLine().getStatusCode();
14        if (statusCode == 200) {
15            System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
16        } else if (statusCode == 204) {
17            System.out.println("success");
18        } else {
19            System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
20            throw new IOException("request failed");
21        }
22    } finally {
23        response.close();
24  }
25}

PHP示例代码：

1try {
2        $resp = $client->request(
3            'GET',
4            'https://api.mch.weixin.qq.com/v3/pay/transactions/id/1217752501201407033233368018?mchid=1230000109', //请求URL
5            [
6                'headers' => [ 'Accept' => 'application/json']
7            ]
8        );
9        $statusCode = $resp->getStatusCode();
10        if ($statusCode == 200) { //处理成功
11            echo "success,return body = " . $resp->getBody()->getContents()."\n";
12        } else if ($statusCode == 204) { //处理成功，无返回Body
13            echo "success";
14        }
15    } catch (RequestException $e) {
16        // 进行错误处理
17        echo $e->getMessage()."\n";
18        if ($e->hasResponse()) {
19            echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
20        }
21        return;
22    }

更多参数、响应详情及错误码请参见微信支付订单号查询订单 / 商户订单号查询订单接口文档。

3.2.5. 【服务端】关闭订单

步骤说明：当商户订单支付失败需要生成新单号重新发起支付，要对原订单号调用关单，避免重复支付；系统下单后，用户支付超时，系统退出不再受理，避免用户继续，请调用关单接口。

注意

关单没有时间限制，建议在订单生成后间隔几分钟（最短5分钟）再调用关单接口，避免出现订单状态同步不及时导致关单失败。
已支付成功的订单不能关闭。

JAVA示例代码：

1public void CloseOrder() throws Exception {
2     
3    //请求URL
4    HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/pay/transactions/out-trade-no/sdkphp12345678920201028112429/close");
5    //请求body参数
6    String reqdata ="{\"mchid\": \""+mchId+"\"}";
7     
8    StringEntity entity = new StringEntity(reqdata,"utf-8");
9    entity.setContentType("application/json");
10    httpPost.setEntity(entity);
11    httpPost.setHeader("Accept", "application/json");
12   
13  //完成签名并执行请求
14    CloseableHttpResponse response = httpClient.execute(httpPost);
15    try {
16        int statusCode = response.getStatusLine().getStatusCode();
17        if (statusCode == 200) {
18            System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
19        } else if (statusCode == 204) {
20            System.out.println("success");
21        } else {
22            System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
23            throw new IOException("request failed");
24        }
25    } finally {
26        response.close();
27    }
28  }

PHP示例代码：

1try {
2    $resp = $client->request(
3        'POST',
4        'https://api.mch.weixin.qq.com/v3/pay/transactions/out-trade-no/{out_trade_no}/close', //请求URL
5        [
6            // JSON请求体
7            'json' => [
8                "mchid " => "1230000109",
9            ],
10            'headers' => [ 'Accept' => 'application/json' ]
11        ]
12    );
13    $statusCode = $resp->getStatusCode();
14    if ($statusCode == 200) { //处理成功
15        echo "success,return body = " . $resp->getBody()->getContents()."\n";
16    } else if ($statusCode == 204) { //处理成功，无返回Body
17        echo "success";
18    }
19  } catch (RequestException $e) {
20    // 进行错误处理
21    echo $e->getMessage()."\n";
22    if ($e->hasResponse()) {
23        echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
24    }
25    return;
26  }

更多参数、响应详情及错误码请参见关闭订单接口文档。

3.2.6. 【服务端】申请交易账单

步骤说明：微信支付按天提供交易账单文件，商户可以通过该接口获取账单文件的下载地址。

JAVA示例代码：

1public void TradeBill() throws Exception {
2   
3    //请求URL
4    URIBuilder uriBuilder = new URIBuilder("https://api.mch.weixin.qq.com/v3/bill/tradebill");
5    uriBuilder.setParameter("bill_date", "2020-11-09");
6    uriBuilder.setParameter("bill_type", "ALL");
7    
8    //完成签名并执行请求
9    HttpGet httpGet = new HttpGet(uriBuilder.build());
10    httpGet.addHeader("Accept", "application/json");
11    CloseableHttpResponse response = httpClient.execute(httpGet);
12    
13        try {
14            int statusCode = response.getStatusLine().getStatusCode();
15            if (statusCode == 200) {
16                System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
17            } else if (statusCode == 204) {
18                System.out.println("success");
19            } else {
20                System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
21                throw new IOException("request failed");
22            }
23        } finally {
24            response.close();
25        }
26}

PHP示例代码：

1try {
2    $resp = $client->request(
3        'GET',
4        'https://api.mch.weixin.qq.com/v3/bill/tradebill?bill_date=2019-06-11&bill_type=ALL', //请求URL
5        [
6            'headers' => [ 'Accept' => 'application/json']
7        ]
8    );
9    $statusCode = $resp->getStatusCode();
10    if ($statusCode == 200) { //处理成功
11        echo "success,return body = " . $resp->getBody()->getContents()."\n";
12    } else if ($statusCode == 204) { //处理成功，无返回Body
13        echo "success";
14    }
15} catch (RequestException $e) {
16    // 进行错误处理
17    echo $e->getMessage()."\n";
18    if ($e->hasResponse()) {
19        echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
20    }
21    return;
22}

更多参数、响应详情及错误码请参见申请交易账单接口文档。

3.2.7. 【服务端】下载账单

步骤说明：通过申请交易账单接口获取到账单下载地址（download_url）后，再通过该接口获取到对应的账单文件，文件内包含交易相关的金额、时间、营销等信息，供商户核对订单、退款、银行到账等情况。

注意

账单文件的下载地址的有效时间为30s。
强烈建议商户将实际账单文件的哈希值和之前从接口获取到的哈希值进行比对，以确认数据的完整性。
该接口响应的信息请求头中不包含微信接口响应的签名值，因此需要跳过验签的流程。
微信在次日9点启动生成前一天的对账单，建议商户10点后再获取。

JAVA示例代码：

1public void DownloadUrl(String download_url) throws Exception{
2  PrivateKey merchantPrivateKey = PemUtil.loadPrivateKey(new ByteArrayInputStream(privateKey.getBytes("utf-8")));
3   
4  //初始化httpClient
5  //该接口无需进行签名验证、通过withValidator((response) -> true)实现
6  httpClient =  WechatPayHttpClientBuilder.create().withMerchant(mchId, mchSerialNo, merchantPrivateKey).withValidator((response) -> true).build();
7   
8  //请求URL
9  //账单文件的下载地址的有效时间为30s
10  URIBuilder uriBuilder = new URIBuilder(download_url);
11  HttpGet httpGet = new HttpGet(uriBuilder.build());
12  httpGet.addHeader("Accept", "application/json");
13   
14  //执行请求
15  CloseableHttpResponse response = httpClient.execute(httpGet);
16    try {
17        int statusCode = response.getStatusLine().getStatusCode();
18        if (statusCode == 200) {
19            System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));
20        } else if (statusCode == 204) {
21            System.out.println("success");
22        } else {
23            System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));
24            throw new IOException("request failed");
25        }
26    } finally {
27        response.close();
28    }
29}

PHP示例代码：

1try {
2    $resp = $client->request(
3        'GET',
4        'https://api.mch.weixin.qq.com/v3/billdownload/file?token=xx', //请求URL
5        [
6            'headers' => [ 'Accept' => 'application/json']
7        ]
8    );
9    $statusCode = $resp->getStatusCode();
10    if ($statusCode == 200) { //处理成功
11        echo "success,return body = " . $resp->getBody()->getContents()."\n";
12    } else if ($statusCode == 204) { //处理成功，无返回Body
13        echo "success";
14    }
15} catch (RequestException $e) {
16    // 进行错误处理
17    echo $e->getMessage()."\n";
18    if ($e->hasResponse()) {
19        echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
20    }
21    return;
22}

更多参数、响应详情及错误码请参见下载账单接口文档。

4. 常见问题

Q：调起H5支付报"商家参数格式有误，请联系商家解决"

A：请按以下几点进行排查：

当前调起H5支付的referer为空导致，一般是因为直接访问页面调起H5支付，请按正常流程进行页面跳转后发起支付，或自行抓包确认referer值是否为空
如果是App里调起H5支付，需要在webview中手动设置referer，如(Map extraHeaders = new HashMap();extraHeaders.put("Referer", "商户申请H5时提交的授权域名");//例如 https://pay.wechatpay.cn )

Q：调起H5支付报"商家存在未配置的参数，请联系商家解决"

A：请按以下几点进行排查：

当前调起H5支付的域名（微信侧从referer中获取）与申请H5支付时提交的授权域名不一致，如需添加或修改授权域名，请登录商户号对应的【商户平台 -> 产品中心 -> 开发配置】自行配置。
如果设置了回跳地址redirect_url，请确认设置的回跳地址的域名与申请H5支付时提交的授权域名是否一致。

Q：调起H5支付报"支付请求已失效，请重新发起支付"

A：统一下单返回的H5_URL生成后，有效期为5分钟，如超时请重新生成H5_URL后再发起支付

Q：调起H5支付报" 请在微信外打开订单，进行支付"

A：H5支付不能直接在微信客户端内调起，请在外部浏览器调起。

Q：调起H5支付报" 签名验证失败"或“系统繁忙，请稍后再试”

A：请按以下几点进行排查：

请确认同一个H5_URL只被一个微信号调起，如果不同微信号调起请重新下单生成新的H5_URL。
如H5_URL有添加redirect_url，请确认参数拼接格式是否有误，是否有对redirect_url的值做urlencode,可参考以下例子格式：

https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx20161110163838f231619da20804912345&package=1037687096&redirect_url=https%3A%2F%2Fwww.wechatpay.com.cn

Q：IOS在使用某些浏览器完成H5支付后会回到safari浏览器

A：对的，返回需要浏览器的schema信息，部分浏览器隐藏了这个信息，在无法拿到schema信息的情况下，就会回到safari浏览器

Q：网络环境未能通过安全验证，请稍后再试

A：请按以下几点进行排查：

商户侧统一下单传的终端IP(spbill_create_ip)与用户实际调起支付时微信侧检测到的终端IP不一致导致的，这个问题一般是商户在统一下单时没有传递正确的终端IP到spbill_create_ip导致，详细可参见客户端ip获取指引
统一下单与调起支付时的网络有变动，如统一下单时是WIFI网络，下单成功后切换成4G网络再调起支付，这样可能会引发我们的正常拦截，请保持网络环境一致的情况下重新发起支付流程

Q：由于商家传入的H5交易参数有误，该笔交易暂时无法完成,请联系商家解决

A：统一下单中 spbill_create_ip 字段必须为客户端IP地址

Q：传递redirect_url safari浏览器时支付完成后会新开一个页面；

A：目前逻辑就是这样设计的，防止商户无限循环调用微信客户端

文档是否有帮助

更多支持

开发文档(服务商)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服