首页成为合作伙伴合作伙伴能力合作伙伴成长文档中心
文档中心
首页接入指引产品中心解决方案文档中心接入微信支付
产品文档通用规则SDK&开发工具更新日志
产品文档
产品文档/
支付产品/
小程序支付/
开发指引/

开发指引

更新时间：2024.11.15

1. 接口规则

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

2. 开发准备

2.1. 搭建和配置开发环境

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

2.2. 业务开发配置

2.2.1. 账号申请指引

  • 小程序开通微信支付，即申请或复用微信支付商户号，申请完小程序后，登录小程序后台。点击左侧导航栏的微信支付，在页面中进行开通。（开通申请要求小程序已发布上线）

  • 点击开通按钮后，有2种方式可以获取微信支付能力，新申请微信支付商户号或绑定一个已有的微信支付商户号，请根据你的业务需要和具体情况选择，只能二选一。开通指引

2.2.2. 服务器配置要求

  1. 小程序访问商户服务都是通过HTTPS,开发部署的时候需要HTTPS服务器。

  2. 服务器域名配置。

    • 每个微信小程序需要事先设置通信域名，小程序只可以跟指定的域名进行网络通信。包括普通 HTTPS 请求(wx.request)、上传文件(wx.uploadFile)、下载文件(wx.downloadFile)和 WebSocket 通信(wx.connectSocket)

    • 从基础库 2.4.0 开始，网络接口允许与局域网 IP 通信，但要注意 不允许与本机 IP 通信

注意

  • 域名只支持 HTTPS (wx.request、wx.uploadFile、wx.downloadFile)和 wss(wx.connectSocket)协议。

  • 域名不能使用 IP 地址（小程序的局域网 IP 除外）或 localhost。

  • 可以配置端口，如 https://myserver.com:8080，但是配置后只能向 https://myserver.com:8080/ 发起请求。如果向 https://myserver.com、https://myserver.com:9091 等 URL 请求则会失败。

  • 如果不配置端口。如 https://myserver.com，那么请求的 URL 中也不能包含端口，甚至是默认的 443 端口也不可以。如果向 https://myserver.com:443 请求则会失败。

  • 域名必须经过 ICP 备案。

  • 出于安全考虑， API.weixin.qq.com 不能被配置为服务器域名，相关API也不能在小程序内调用。 开发者应将AppSecret 保存到后台服务器中，通过服务器使用 getAccessToken 接口获取 access_token，并调用相关 API。

  • 不支持配置父域名，使用子域名。

  • 可查阅小程序网络请求以了解更多信息。

3. 快速接入

3.1. 业务流程图

重点步骤说明：

步骤4： 用户下单发起支付，商户可通过JSAPI下单创建支付订单。

步骤9： 商户小程序内使用小程序调起支付API（wx.requestPayment）发起微信支付，详见小程序API文档。

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

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

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

本章节展示了如何使用微信支付服务端 SDK 快速接入小程序支付产品，完成与微信支付对接的部分。

注意

  • 文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。

  • 以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。

3.2.1. 【服务端】小程序下单

步骤说明：

用户通过商户小程序进入商户网页，当用户选择相关商品购买时，商户系统先调用该接口在微信支付服务后台生成预支付交易单。

JAVA代码示例：

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

PHP代码示例：

1try {
2    $resp = $client->request(
3        'POST',
4        'https://api.mch.weixin.qq.com/v3/pay/transactions/jsapi', //请求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" => "1230000109",
14                "description" => "Image形象店-深圳腾大-QQ公仔",
15                "notify_url" => "https://www.weixin.qq.com/wxpay/pay.php",
16                "payer" => [
17                    "openid" => "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",
18                ],
19                "out_trade_no" => "1217752501201407033233368018",
20                "goods_tag" => "WXG",
21                "appid" => "wxd678efh567hg6787",
22                "attach" => "自定义数据说明",
23                "scene_info" => [
24                    "store_info" => [
25                        "address" => "广东省深圳市南山区科技中一道10000号",
26                        "area_code" => "440305",
27                        "name" => "腾讯大厦分店",
28                        "id" => "0001",
29                    ],
30                    "device_id" => "013467007045764",
31                    "payer_client_ip" => "14.23.150.211",
32                ]
33            ],
34            'headers' => [ 'Accept' => 'application/json' ]
35        ]
36    );
37    $statusCode = $resp->getStatusCode();
38    if ($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    // 进行错误处理
45    echo $e->getMessage()."\n";
46    if ($e->hasResponse()) {
47        echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";
48    }
49    return;
50}

重要入参说明：

  • out_trade_no： 商户系统内部订单号，只能是数字、大小写字母_-*且在同一个商户号下唯一。

  • description： 商品描述。

  • notify_url： 支付回调通知URL，该地址必须为直接可访问的URL，不允许携带查询串。

  • total： 订单总金额，单位为分。

  • OpenID： OpenID是微信用户在AppID下的唯一用户标识（AppID不同，则获取到的OpenID就不同），可用于永久标记一个用户。OpenID获取方式请参考以下文档小程序获取OpenID、公众号获取OpenID、App获取OpenID。

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

3.2.2.【客户端】小程序调起支付API

步骤说明： 通过JSAPI下单API成功获取预支付交易会话标识（prepay_id） 后，需要通过JSAPI调起支付API来调起微信支付收银台。

注意

  • 此API需要将请求参数进行签名（参与签名的参数为：AppID、timeStamp、nonceStr、package，参数区分大小写）。

  • AppID必须为最后拉起收银台的小程序AppID。

1wx.requestPayment(
2{
3"timeStamp": "1414561699",
4"nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS",
5"package": "prepay_id=wx201410272009395522657a690389285100",
6"signType": "RSA",
7"paySign": "oR9d8PuhnIc+YZ8cBHFCwfgpaK9gd7vaRvkYD7rthRAZ\/X+QBhcCYL21N7cHCTUxbQ+EAt6Uy+lwSN22f5YZvI45MLko8Pfso0jm46v5hqcVwrk6uddkGuT+Cdvu4WBqDzaDjnNa5UK3GfE1Wfl2gHxIIY5lLdUgWFts17D4WuolLLkiFZV+JSHMvH7eaLdT9N5GBovBwu5yYKUR7skR8Fu+LozcSqQixnlEZUfyE55feLOQTUYzLmR9pNtPbPsu6WVhbNHMS3Ss2+AehHvz+n64GDmXxbX++IOBvm2olHu3PsOUGRwhudhVf7UcGcunXt8cqNjKNqZLhLw4jq\/xDg==",
8"success":function(res){},
9"fail":function(res){},
10"complete":function(res){}
11})

重要入参说明：

  • package： JSAPI下单接口返回的prepay_id参数值，提交格式如：prepay_id=***。

  • signType： 该接口V3版本仅支持RSA。

  • paySign： 签名。

paySign生成规则、响应详情及错误码请参见 小程序调起支付接口文档。

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或JSAPI支付。

Q：调起小程序支付报“商户号该产品权限未开通”

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

  1. 请检查请求参数是否正确，如请求参数中的AppID是否与小程序对应。

  2. AppID对应的小程序是否有开通小程序支付功能，权限状态是否正常，可登录商户平台核实。

  3. AppID与商户号是否存在绑定关系，可登录商户平台核实。

Q：小程序开通微信支付有哪几种方式

A：可通过以下两种方式开通:

  1. 绑定已有公众号的微信支付：耗时10分钟即可，只需原有公众号开通微信支付，小程序微信支付可以选择绑定原来的微信支付商户号，即可开通成功。

  2. 新申请微信支付：耗时需要1-5个工作日，需要提交和申请小程序一样的资料进行审核，审核通过后才能开通成功。

 

更多支持
开发文档(商户)开发文档(V2版)开发者社区微信开放平台微信公众平台腾讯客服
更多技术问题
技术咨询
1. 接口规则
2. 开发准备
2.1. 搭建和配置开发环境
2.2. 业务开发配置
2.2.1. 账号申请指引
2.2.2. 服务器配置要求
3. 快速接入
3.1. 业务流程图
3.2. API接入（含示例代码）
3.2.1. 【服务端】小程序下单
3.2.2.【客户端】小程序调起支付API
3.2.3. 【服务端】接收支付结果通知
3.2.4. 【服务端】查询订单
3.2.5. 【服务端】关闭订单
3.2.6. 【服务端】申请交易账单
3.2.7. 【服务端】下载账单
4. 常见问题
Q：在小程序内通过外部H5页面调起支付报错
Q：调起小程序支付报“商户号该产品权限未开通”
Q：小程序开通微信支付有哪几种方式
反馈
咨询
目录
置顶
Powered By Tencent & Tenpay Copyright 2005-2024 Tenpay All Rights Reserved.
Powered By Tencent & Tenpay
Copyright 2005-2024 Tenpay All Rights Reserved.