开发指引
更新时间：2024.12.27# 1. 接口规则
为了在保证支付安全的前提下，带给商户简单、一致且易用的开发体验，我们推出了全新的微信支付APIv3接口。该版本API的具体规则请参考APIv3接口规则。
# 2. 开发准备
# 2.1. 搭建和配置开发环境
开发者应当依据自身的编程语言来构建并配置相应的开发环境。
# 2.2. 业务开发配置
合单支付目前支持在微信外H5、App、JSAPI、小程序、Native扫码5个场景使用，下面为你介绍App场景业务开发配置。
# 2.2.1. 账号申请指引
a、小程序开通微信支付，即申请或复用微信支付商户号 申请完小程序后，登录小程序后台 (opens new window)。点击左侧导航栏的微信支付，在页面中进行开通。（开通申请要求小程序已发布上线）
b、点击开通按钮后，有2种方式可以获取微信支付能力，新申请微信支付商户号或绑定一个已有的微信支付商户号，请根据你的业务需要和具体情况选择，只能二选一。详见微信支付商户接入指引 (opens new window)。
# 2.2.2. 服务器配置要求
a、小程序访问商户服务都是通过HTTPS,开发部署的时候需要HTTPS服务器。
b、服务器域名配置
① 每个微信小程序需要事先设置通讯域名，小程序只可以跟指定的域名进行网络通信。包括普通 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 (opens new window) 接口获取 access_token，并调用相关 API。 - 不支持配置父域名，使用子域名。
- 可查阅小程序网络请求 (opens new window)以了解更多信息。
# 3. 快速接入
# 3.1. 业务流程图
业务流程时序图如下。
重点步骤说明：
步骤1：用户在商户侧发起支付请求，商户先通过后台接口合单下单-小程序接口创建合单支付订单。
步骤2：商户再根据用户发起支付请求的具体场景通过小程序页面调起微信支付收银台，完成支付请求。
步骤3：用户支付成功后，商户可接收到支付结果回调通知。
步骤4：如果商户长时间未收到回调通知，可通过合单查询订单接口主动查询订单支付状态。
# 3.2. API接入（含示例代码）
文档展示了如何使用微信支付服务端 SDK 快速接入商家券产品，完成与微信支付对接的部分。
注意
- 文档中的代码示例是用来阐述 API 基本使用方法，代码中的示例参数需替换成商户自己账号及请求参数才能跑通。
- 以下接入步骤仅提供参考，请商户结合自身业务需求进行评估、修改。
# 3.2.1. 【服务端】合单下单-小程序
步骤说明：用户在商户侧选择商品下单购买时，商户系统先调用该接口在微信支付服务后台生成预支付交易单，然后使用我们提供的客户端方法（下文介绍）调起微信支付收银台，即可完成支付。
示例代码：
示例代码
1public void CombineJsapiPrepay() throws Exception{2 //请求URL3 HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/combine-transactions/jsapi");4 5 // 请求body参数6 String reqdata = "{"7 + "\"combine_out_trade_no\":\"1217752501201407033233368018\","8 + "\"combine_mchid\":\"1230000109\","9 + "\"combine_appid\":\"wxd678efh567hg6787\","10 + "\"scene_info\": {"11 + "\"device_id\":\"POS1:1\","12 + "\"payer_client_ip\":\"14.17.22.32\""13 + "},"14 + "\"sub_orders\": ["15 + "{"16 + "\"mchid\":\"1230000109\","17 + "\"attach\":\"深圳分店\","18 + "\"amount\": {"19 + "\"total_amount\":10,"20 + "\"currency\":\"CNY\""21 + "},"22 + "\"out_trade_no\":\"20150806125346\","23 + "\"sub_mchid\":\"1900000109\","24 + "\"description\":\"腾讯充值中心-QQ会员充值\""25 + "}"26 + "],"27 + "\"combine_payer_info\": {"28 + "\"openid\":\"oUpF8uMuAJO_M2pxb1Q9zNjWeS6o\""29 + "},"30 + "\"time_start\":\"2018-06-08T10:34:56+08:00\","31 + "\"time_expire\":\"2018-06-08T10:34:56+08:00\","32 + "\"notify_url\":\"https://yourapp.com/notify\""33 + "}";34 StringEntity entity = new StringEntity(reqdata,"utf-8");35 entity.setContentType("application/json");36 httpPost.setEntity(entity);37 httpPost.setHeader("Accept", "application/json");3839 //完成签名并执行请求40 CloseableHttpResponse response = httpClient.execute(httpPost);4142 try {43 int statusCode = response.getStatusLine().getStatusCode();44 if (statusCode == 200) { //处理成功45 System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));46 } else if (statusCode == 204) { //处理成功，无返回Body47 System.out.println("success");48 } else {49 System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));50 throw new IOException("request failed");51 }52 } finally {53 response.close();54 }55}1try {2 $resp = $client->request(3 'POST',4 'https://api.mch.weixin.qq.com/v3/combine-transactions/jsapi', //请求URL5 [6 // JSON请求体7 'json' => [8 "combine_out_trade_no" => "1217752501201407033233368018",9 "combine_mchid" => "1230000109",10 "combine_appid" => "wxd678efh567hg6787",11 "scene_info" => [12 "device_id" => "POS1:1",13 "payer_client_ip" => "14.17.22.32",14 ],15 "sub_orders" => [16 [17 "mchid" => "1230000109",18 "attach" => "深圳分店",19 "amount" => [20 "total_amount" => 10,21 "currency" => "CNY",22 ],23 "out_trade_no" => "20150806125346",24 "sub_mchid" => "1900000109",25 "description" => "腾讯充值中心-QQ会员充值",26 ],27 ],28 "combine_payer_info" => [29 "openid" => "oUpF8uMuAJO_M2pxb1Q9zNjWeS6o",30 ],31 "time_start" => "2018-06-08T10:34:56+08:00",32 "time_expire" => "2018-06-08T10:34:56+08:00",33 "notify_url" => "https://yourapp.com/notify",34 ],35 'headers' => [ 'Accept' => 'application/json' ]36 ]37 );38 $statusCode = $resp->getStatusCode();39 if ($statusCode == 200) { //处理成功40 echo "success,return body = " . $resp->getBody()->getContents()."\n";41 } else if ($statusCode == 204) { //处理成功，无返回Body42 echo "success";43 }44} catch (RequestException $e) {45 // 进行错误处理46 echo $e->getMessage()."\n";47 if ($e->hasResponse()) {48 echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";49 }50 return;51}重要入参说明：
- out_trade_no：商户系统内部订单号，可以是数字、大小写字母_-*的任意组合，且在同一个商户号下唯一。
- description：商品描述。
- notify_url：支付回调通知URL，该地址必须为直接可访问的URL，不允许携带查询串。
- total：订单总金额，单位为分。
- OpenID：OpenID是微信用户在AppID下的唯一用户标识（AppID不同，则获取到的OpenID就不同），可用于永久标记一个用户。OpenID获取方式请参考以下文档小程序获取OpenID (opens new window)、公众号获取OpenID (opens new window)、App获取OpenID (opens new window)。
更多参数、响应详情及错误码请参见合单下单-小程序。
# 3.2.2. 【客户端】小程序调起支付API
步骤说明：通过小程序下单API成功获取预支付交易会话标识（prepay_id）后，需要通过小程序调起支付API来调起微信支付收银台。
注意
- 此API需要将请求参数进行签名（参与签名的参数为：
appId、timeStamp、nonceStr、package，参数区分大小写）。 appId必须为最后拉起收银台的小程序appid。
示例代码：
1wx.requestPayment(2{3"timeStamp": "1414561699",4"nonceStr": "5K8264ILTKCH16CQ2502SI8ZNMTM67VS",5"package": "prepay_id=up_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： 合单小程序下单接口返回的prepay_id参数值，提交格式如：
prepay_id=*** - signType： 该接口V3版本仅支持RSA
- paySign： 签名
- nonceStr： 自定义随机数
paySign生成规则、响应详情及错误码请参见小程序调起支付接口文档。
# 3.2.3.【服务端】接收支付结果通知
步骤说明：当用户完成支付，微信会把相关支付结果将通过异步回调的方式通知商户，商户需要接收处理，并按文档规范返回应答。
- 支付结果通知的地址需要在请求App下单API时传入
notify_url参数中。 - 支付结果通知是以POST 方法访问商户设置的通知URL，通知的数据以JSON 格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情。
- 加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名，并将签名值放在通知的HTTP头
Wechatpay-Signature。商户应当验证签名，以确认请求来自微信，而不是其他的第三方。签名验证的算法请参考 《微信支付API v3签名验证》。 - 支付结果通知HTTP应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx。
- 商户成功接收到回调通知后应返回成功的HTTP应答码为200或204
- 同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。
- 后台通知交互时，如果微信收到商户的应答不符合规范或超时，微信会判定本次通知失败，重新发送通知，直到成功为止，但微信不保证通知最终一定能成功。
特别提醒：
- 商户系统对于支付结果通知的内容一定要做签名验证,并校验返回的订单金额是否与商户侧的订单金额一致，防止数据泄露导致出现“假通知”，造成资金损失。
- 当收到通知进行处理时，首先检查对应业务数据的状态，判断该通知是否已经处理过，如果没有处理过再进行处理，如果处理过直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
更多参数、响应详情及错误码请参见支付结果通知API接口文档。
# 3.2.4. 【服务端】合单查询订单
步骤说明：当商户后台、网络、服务器等出现异常，商户系统最终未接收到支付结果通知时商户可通过查询订单接口核实订单支付状态。
示例代码：
示例代码
1public void QueryOrder() throws Exception {23 //请求URL4 URIBuilder uriBuilder = new URIBuilder("https://api.mch.weixin.qq.com/v3/combine-transactions/out-trade-no/P11093730578574");5 uriBuilder.setParameter("mchid", mchId);67 //完成签名并执行请求8 HttpGet httpGet = new HttpGet(uriBuilder.build());9 httpGet.addHeader("Accept", "application/json");10 CloseableHttpResponse response = httpClient.execute(httpGet);1112 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}1try {2 $resp = $client->request(3 'GET',4 'https://api.mch.weixin.qq.com/v3/combine-transactions/out-trade-no/P11093730578574', //请求URL5 [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) { //处理成功，无返回Body13 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}注意
- 查询订单可通过合单商户订单号查询。
更多参数、响应详情及错误码请参见查询订单API接口文档。
# 3.2.5. 【服务端】合单关闭订单
步骤说明：当商户订单支付失败需要生成新单号重新发起支付，要对原订单号调用关单，避免重复支付；系统下单后，用户支付超时，系统退出不再受理，避免用户继续，请调用关单接口。
示例代码：
示例代码
1public void CombineCloseOrder() throws Exception{23 //请求URL4 HttpPost httpPost = new HttpPost("https://api.mch.weixin.qq.com/v3/combine-transactions/out-trade-no/{combine_out_trade_no}/close");5 // 请求body参数6 String reqdata = "{"7 + "\"combine_appid \":\"wxd678efh567hg6787\","8 + "\"combine_out_trade_no\":\"P20150806125346\","9 + "\"sub_orders\": ["10 + "{"11 + "\"mchid\":\"1900000109\","12 + "\"out_trade_no\":\"20150806125346\","13 + "\"sub_mchid\":\"1230000109\","14 + "\"description\":\"腾讯充值中心-QQ会员充值\""15 + "}"16 + "]"17 + "}";18 StringEntity entity = new StringEntity(reqdata,"utf-8");19 entity.setContentType("application/json");20 httpPost.setEntity(entity);21 httpPost.setHeader("Accept", "application/json");2223 //完成签名并执行请求24 CloseableHttpResponse response = httpClient.execute(httpPost);2526 try {27 int statusCode = response.getStatusLine().getStatusCode();28 if (statusCode == 200) { //处理成功29 System.out.println("success,return body = " + EntityUtils.toString(response.getEntity()));30 } else if (statusCode == 204) { //处理成功，无返回Body31 System.out.println("success");32 } else {33 System.out.println("failed,resp code = " + statusCode+ ",return body = " + EntityUtils.toString(response.getEntity()));34 throw new IOException("request failed");35 }36 } finally {37 response.close();38 }39}1try {2 $resp = $client->request(3 'POST',4 'https://api.mch.weixin.qq.com/v3/combine-transactions/out-trade-no/{combine_out_trade_no}/close', //请求URL5 [6 // JSON请求体7 'json' => [8 "combine_appid " => "wxd678efh567hg6787",9 "combine_out_trade_no" => "P20150806125346",10 "sub_orders" => [11 [12 "mchid" => "1900000109",13 "out_trade_no" => "20150806125346",14 "sub_mchid" => "1230000109",15 "description" => "腾讯充值中心-QQ会员充值",16 ],17 ]18 ],19 'headers' => [ 'Accept' => 'application/json' ]20 ]21 );22 $statusCode = $resp->getStatusCode();23 if ($statusCode == 200) { //处理成功24 echo "success,return body = " . $resp->getBody()->getContents()."\n";25 } else if ($statusCode == 204) { //处理成功，无返回Body26 echo "success";27 }28} catch (RequestException $e) {29 // 进行错误处理30 echo $e->getMessage()."\n";31 if ($e->hasResponse()) {32 echo "failed,resp code = " . $e->getResponse()->getStatusCode() . " return body = " . $e->getResponse()->getBody() . "\n";33 }34 return;35}注意
- 订单生成后不能马上调用关单接口，最短调用时间间隔为5分钟。
- 已支付成功的订单不能关闭。
更多参数、响应详情及错误码请参见合单关单API接口文档。
# 3.2.6. 【服务端】申请交易账单
步骤说明：微信支付按天提供交易账单文件，商户可以通过该接口获取账单文件的下载地址。
示例代码：
示例代码
1public void TradeBill() throws Exception {23 //请求URL4 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");78 //完成签名并执行请求9 HttpGet httpGet = new HttpGet(uriBuilder.build());10 httpGet.addHeader("Accept", "application/json");11 CloseableHttpResponse response = httpClient.execute(httpGet);1213 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}1try {2 $resp = $client->request(3 'GET',4 'https://api.mch.weixin.qq.com/v3/bill/tradebill?bill_date=2019-06-11&sub_mchid=1900000001&bill_type=ALL', //请求URL5 [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) { //处理成功，无返回Body13 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）后，再通过该接口获取到对应的账单文件，文件内包含交易相关的金额、时间、营销等信息，供商户核对订单、退款、银行到账等情况。
示例代码：
示例代码
1public void TradeBill() throws Exception {23 //请求URL4 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");78 //完成签名并执行请求9 HttpGet httpGet = new HttpGet(uriBuilder.build());10 httpGet.addHeader("Accept", "application/json");11 CloseableHttpResponse response = httpClient.execute(httpGet);1213 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}1try {2 $resp = $client->request(3 'GET',4 'https://api.mch.weixin.qq.com/v3/bill/tradebill?bill_date=2019-06-11&sub_mchid=1900000001&bill_type=ALL', //请求URL5 [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) { //处理成功，无返回Body13 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}注意
- 账单文件的下载地址的有效时间为30s。
- 强烈建议商户将实际账单文件的哈希值和之前从接口获取到的哈希值进行比对，以确认数据的完整性。
更多参数、响应详情及错误码请参见下载账单接口文档。
# 4. 常见问题
问: 获取OpenID接口报“此公众号并没有这些scope的权限，错误码10005”，如下图所示。
答: 请按以下步骤进行排查：
- 建议检查一下公众号的功能。比如是不是在订阅号/未认证的公众号里面尝试调用认证服务号的功能。
- 确认AppID是否认证过期或者AppID填写错误。
- 请尝试使用snsapi_userinfo的授权登录方式。
问：获取OpenID接口报“redirect_url域名与后台配置不一致，错误码：10003”。
答：请按以下步骤进行排查：
- 本错误是公众号获取OpenID接口报的错误，可参考文档检查是否符合开发规范：网页授权 (opens new window)
- 检查下单接口传的AppID与获取OpenID接口的AppID是否同一个（需一致）。
- 检查AppID对应的公众号后台 (opens new window)，是否配置的授权域名和获取OpenID的域名一致。授权域名配置路径：【公众平台 (opens new window)-> 设置-> 公众号设置-> 功能设置–> 网页授权域名】。
文档是否有帮助
