开发指引

更新时间：2025.01.06

1. 接口规则

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

2. 开发环境搭建

为了帮助开发者调用开放接口，我们提供了Java、PHP、GO语言版本的开发库，封装了签名生成、签名验证、敏感信息加/解密、媒体文件上传等基础功能

JAVA

2.1.1. 使用条件

WechatPay merchant account
Java 1.8 or later
Maven or Gradle;
0.4.6 or later version of the Java httpClient SDK

2.1.2. 安装

Gradle：在你的 build.gradle 文件中加入如下的依赖

1implementation 'com.github.wechatpay-apiv3:wechatpay-apache-httpclient:0.4.7'

Maven：在 pom.xml 文件中加入以下依赖

1<dependency>
2<groupId>com.github.wechatpay-apiv3</groupId>
3<artifactId>wechatpay-apache-httpclient</artifactId>
4<version>0.4.7</version>
5</dependency>

2.1.3. 初始化

用WechatPayHttpClientBuilder初始化创建一个httpClient，httpClient将被用于发送请求调用微信支付接口。用CertificatesManager初始化一个verifier实例，用于验证签名。

1    private CloseableHttpClient httpClient;
2    private CertificatesManager certificatesManager;
3    private Verifier verifier;
4
5    @Before
6    //initialize verifier and build httpClient
7    public void setup() throws GeneralSecurityException, IOException, HttpCodeException, NotFoundException {
8
9        PrivateKey merchantPrivateKey = PemUtil.loadPrivateKey(privateKey);
10        certificatesManager = CertificatesManager.getInstance();
11        certificatesManager.putMerchant(merchantId, new WechatPay2Credentials(merchantId,
12                        new PrivateKeySigner(merchantSerialNumber, merchantPrivateKey)),
13                apiV3Key.getBytes(StandardCharsets.UTF_8));
14        verifier = certificatesManager.getVerifier(merchantId);
15        WechatPayHttpClientBuilder builder = WechatPayHttpClientBuilder.create()
16                .withMerchant(merchantId, merchantSerialNumber, merchantPrivateKey)
17                .withValidator(new WechatPay2Validator(verifier));
18        httpClient = builder.build();
19    }

2.1.4. 通用功能

敏感信息加密

1    @Test
2    public void encryptedTest() throws IllegalBlockSizeException {
3        String text = "helloWorld";
4        String transformation = "RSA/ECB/PKCS1Padding";
5        String encryptedText = RsaCryptoUtil.encrypt(text, verifier.getValidCertificate(), transformation);
6        System.out.println(encryptedText);
7    }

敏感信息解密

1    @Test
2    public void decryptedTest() throws BadPaddingException {
3        String encryptedText = OBTgun4jiN13n3nmSg8v0MNDMy3mbs380yq4GrgO8vwCqXnvrWxwo3jUCNY2UY7MIOtv/SD8ke64MxcSB0hn5EzKv1LOLprI3NvvmNLS4C3SBulxpZG62RYp1+8FgwAI4M//icXvjtZWVH4KVDg==";
4        String transformation = "RSA/ECB/PKCS1Padding";
5        String decryptedText = RsaCryptoUtil.decrypt(encryptedText, PemUtil.loadPrivateKey(privateKey), transformation);
6        assert("helloWorld".equals(decryptedText));
7    }

Golang

2.2.1. 使用条件

WechatPay merchant account
GO SDK 0.2.13 or later version

2.2.2. 安装

1. 使用 Go Modules 管理你的项目

如果你的项目还不是使用 Go Modules 做依赖管理，在项目根目录下执行：

go mod init

2. 无需 clone 仓库中的代码，直接在项目目录中执行：

go get -u github.com/wechatpay-apiv3/wechatpay-go

来添加依赖，完成 go.mod 修改与 SDK 下载

2.2.3. 初始化

初始化Client并向Client中加载商户号，私钥，API V3 key，商户证书和序列号，用于之后发送接口请求。

1import (
2   "context"
3   "crypto/rand"
4   "crypto/rsa"
5   "crypto/x509"
6   "encoding/base64"
7   "fmt"
8   "github.com/wechatpay-apiv3/wechatpay-go/core"
9   "github.com/wechatpay-apiv3/wechatpay-go/core/option"
10   "github.com/wechatpay-apiv3/wechatpay-go/utils"
11   "log"
12   "net/http"
13)
14
15var (
16   mchID                      = ""                  // merchant id
17   mchCertificateSerialNumber = "" // merchant certificate serial number
18   mchAPIv3Key                = ""                  // merchant api v3 key
19   header                     = make(http.Header)
20   ctx                        = context.Background()
21   cert                       *x509.Certificate
22   mchPrivateKey              *rsa.PrivateKey
23   client                     *core.Client
24   err                        error
25)
26
27func setup() {
28   //Load platform certificate
29   cert, err = utils.LoadCertificateWithPath("Path/To/Platform/Cert")
30   if err != nil {
31      log.Fatal(err)
32   }
33   // Load private key
34   mchPrivateKey, err = utils.LoadPrivateKeyWithPath("Path/To/Private/Key")
35   if err != nil {
36      log.Fatal("load merchant private key error")
37   }
38   // Initialize client which is capable to update platform certificate periodically
39   opts := []core.ClientOption{
40      option.WithWechatPayAutoAuthCipher(mchID, mchCertificateSerialNumber, mchPrivateKey, mchAPIv3Key),
41   }
42   client, err = core.NewClient(ctx, opts...)
43   if err != nil {
44      log.Fatalf("new wechat pay client err:%s", err)
45   }
46}

2.2.4. 通用功能

敏感信息加密

1
2func Encryption(t *testing.T) {
3	var testRSACryptoUtilMchCertificateStr = `-----BEGIN CERTIFICATE-----
4	-----END CERTIFICATE-----`
5	testRSACryptoUtilCertificate, _ = LoadCertificate(testRSACryptoUtilMchCertificateStr)
6   const message = "hello world"
7   
8   // 使用OAEP padding方式对证书加密
9   ciphertext, _ := EncryptOAEPWithCertificate(message, testRSACryptoUtilCertificate)
10   
11   // 使用PKCS1 padding对证书加密
12   ciphertext, _ := EncryptPKCS1v15WithCertificate(message, testRSACryptoUtilCertificate)
13}
14

敏感信息解密

1func TestDecryption(t *testing.T) {
2	var testRSACryptoUtilPrivateKeyStr = `-----BEGIN PRIVATE KEY-----
3-----END PRIVATE KEY-----`
4	testRSACryptoUtilPrivateKey, _ = LoadPrivateKey(testingKey(testRSACryptoUtilPrivateKeyStr))
5	const ciphertext = ""
6
7	// 使用PKCS1 padding进行私钥解密
8	decryptMessage, _ := DecryptPKCS1v15(ciphertext, testRSACryptoUtilPrivateKey)
9
10	// 使用OAEP padding方式私钥解密
11	decryptMessage, _ := DecryptOAEP(ciphertext, testRSACryptoUtilPrivateKey)
12}

PHP

2.3.1. 使用条件

Guzzle 7.0，PHP >= 7.2.5
Guzzle 6.5，PHP >= 7.1.2
项目已支持 PHP 8。

2.3.2. 安装

推荐使用 PHP 包管理工具 Composer 安装 SDK：

composer require wechatpay/wechatpay

2.3.3. 初始化

初始化Client并向Client中加载商户号，私钥，API V3 key，商户证书和序列号，用于之后发送接口请求。

1
2require_once('vendor/autoload.php');
3
4use WeChatPay\Builder;
5use WeChatPay\Crypto\Rsa;
6use WeChatPay\Util\PemUtil;
7
8$merchantId = '190000****';
9$merchantPrivateKeyFilePath = 'file:///path/to/merchant/apiclient_key.pem';
10$merchantPrivateKeyInstance = Rsa::from($merchantPrivateKeyFilePath, Rsa::KEY_TYPE_PRIVATE);
11$merchantCertificateSerial = '3775B6A45ACD588826D15E583A95F5DD********';
12$platformCertificateFilePath = 'file:///path/to/wechatpay/cert.pem';
13$platformPublicKeyInstance = Rsa::from($platformCertificateFilePath, Rsa::KEY_TYPE_PUBLIC);
14$platformCertificateSerial = PemUtil::parseCertificateSerialNo($platformCertificateFilePath);
15
16// init a API V3 instance
17$instance = Builder::factory([
18    'mchid'      => $merchantId,
19    'serial'     => $merchantCertificateSerial,
20    'privateKey' => $merchantPrivateKeyInstance,
21    'certs'      => [
22        $platformCertificateSerial => $platformPublicKeyInstance,
23    ],
24]); 
25

2.3.4. 通用功能

敏感信息加密

1    $encryptor = static function(string $msg) use ($platformPublicKeyInstance): string {
2        return Rsa::encrypt($msg, $platformPublicKeyInstance, OPENSSL_PKCS1_PADDING);
3    };
4	$encryptedMsg =  $encryptor('HelloWorld');

敏感信息解密

1    $decryptor = static function(string $msg) use ($merchantPrivateKeyInstance): string {
2        return Rsa::decrypt($msg, $merchantPrivateKeyInstance, OPENSSL_PKCS1_PADDING);
3    };
4	$decryptedMsg =  $decryptor('ciphertext');

3. 业务时序图

3.1. 业务时序图

3.2. API接入示例

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

注意

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

3.2.1 下单

步骤说明：通过本接口提交微信支付扫码支付订单，获取二维码对应的code_url。

代码示例 - JAVA：

1    @Test
2    //Call Unified Order API
3    public void unifiedOrderTest() throws IOException {
4      String unifiedOrderBody = String.join("\n" ,
5                		"{",
6                        "    'sp_mchid': '10000100',",
7                        "    'sp_appid': 'wxdace645e0bc2c424',",
8                        "    'description': 'QR code payment test',",
9                        "    'sub_mchid': '20000100',",
10                        "    'trade_type': 'NATIVE',",
11                        "    'merchant_category_code': '4111',",
12                        "    'notify_url': 'http://wxpay.weixin.qq.com/pub_v3/pay/notify.v3.php',",
13                        "    'out_trade_no': 'YX201710140020Z',",
14                        "    'amount': {",
15                        "        'total': 50,",
16                        "        'currency': 'HKD'",
17                        "    },",
18                        "    'detail': {",
19                        "        'receipt_id': '1128',",
20                        "        'cost_price': 2,",
21                        "        'goods_detail': [",
22                        "            {",
23                        "                'goods_id': 'iphone6s_16G',",
24                        "                'wxpay_goods_id': '5732',",
25                        "                'goods_name': 'iPhone6s 16G',",
26                        "                'quantity': 1,",
27                        "                'price': 10",
28                        "            }",
29                        "        ]",
30                        "    }",
31                        "}").replace("'","\"");
32        HttpPost httpPost = new HttpPost("https://apihk.mch.weixin.qq.com/v3/global/transactions/native");
33        httpPost.addHeader("Accept", "application/json");
34        httpPost.addHeader("Content-type", "application/json; charset=utf-8");
35        httpPost.setEntity(new StringEntity(unifiedOrderBody));
36        CloseableHttpResponse response = httpClient.execute(httpPost);
37        //Process the response
38    }

示例代码 - GO：

1//Call unified order API
2func unifiedOrder() {
3   orderRequestBody := `{
4    "sp_appid": "wxdace645e0bc2c424",
5    "sp_mchid": "10000100",
6    "sub_mchid": "20000100",
7    "out_trade_no": "YX201710140020Z",
8    "merchant_category_code": "4111",
9    "notify_url": "https://wxpay.wxutil.com/pub_v2/pay/notify.v2.php",
10    "trade_type": "NATIVE",
11    "amount": {
12        "total": 10,
13        "currency": "HKD"
14    },
15    "attach": "QR code test",
16    "description": "QR code test",
17    "goods_tag": "001",
18    "detail": {
19        "cost_price": 10000,
20        "receipt_id": "1234",
21        "goods_detail": [
22            {
23                "goods_id": "iphone6s_16G",
24                "wxpay_goods_id": "1001",
25                "goods_name": "iPhone6s 16G",
26                "quantity": 1,
27                "price": 10
28            }
29        ]
30    },
31    "scene_info": {
32        "payer_client_ip": "14.23.150.211",
33        "device_ip": "59.37.125.32",
34        "device_id": "013467007045764",
35        "operator_id": "P001",
36        "store_info": {
37            "id": "SZTX001"
38        }
39    }
40}`
41   result, err := client.Post(ctx, "https://apihk.mch.weixin.qq.com/v3/global/transactions/native", orderRequestBody)
42   if err != nil {
43      // Process error
44   }
45   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
46}

示例代码 - PHP：

1// Call Unified Order API
2public function unifiedOrder($instance){
3    try {
4        $resp = $instance
5            ->chain('v3/global/transactions/native')
6            ->post(['json' => [
7                'sp_appid'     => 'wxdace645e0bc2c424',
8                'sp_mchid'     => '10000100',
9                'sub_mchid'    => '20000100',
10                'out_trade_no' => 'YX201710140020Z',
11                'merchant_category_code' => '4111',
12                'notify_url'   => 'https://weixin.qq.com/',
13                'trade_type'   => 'NATIVE',
14                'amount'       => [
15                    'total'    => 1,
16                    'currency' => 'USD'
17                ],
18                'attach'  => 'QR code test',
19                'description'  => 'Image形象店-深圳腾大-QQ公仔',
20                'goods_tag'  => '001'
21            ]]);
22
23        echo $resp->getStatusCode(), PHP_EOL;
24        echo $resp->getBody(), PHP_EOL;
25    } catch (Exception $e) {
26        // EXception handling
27        echo $e->getMessage(), PHP_EOL;
28        if ($e instanceof \GuzzleHttp\Exception\RequestException && $e->hasResponse()) {
29            $r = $e->getResponse();
30            echo $r->getStatusCode() . ' ' . $r->getReasonPhrase(), PHP_EOL;
31            echo $r->getBody(), PHP_EOL, PHP_EOL, PHP_EOL;
32        }
33        echo $e->getTraceAsString(), PHP_EOL;
34    }
35}

重要参数：

out_trade_no: 商户系统内部订单号

notify_url: 接受异步支付结果回调通知的地址，通知url必须为外网可访问的url，不能携带参数。请使用https协议链接

其他重要参数请前往Native支付下单API文档页面参考。

3.2.2 查询订单

步骤说明：商户在用户下单一定时间后，需主动进行查单以确认订单状态。

代码示例 - JAVA：

1
2    @Test
3    //Call query order API
4    public void queryOrderTest() throws IOException {
5        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/transactions/id/" +
6                "4200123456789000?sub_mchid=100012321&sp_mchid=1900000000");
7        httpGet.addHeader("Accept", "application/json");
8        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
9        CloseableHttpResponse response = httpClient.execute(httpGet);
10        //Process the response 
11    }
12

示例代码 - GO：

1
2//Call query order API
3func queryOrder() {
4   result, err := client.Get(ctx, "https://apihk.mch.weixin.qq.com/v3/global/transactions/id/4200000000000000?sub_mchid=100012321&sp_mchid=1900000000")
5   if err != nil {
6      // Process error
7   }
8   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
9}

示例代码 - PHP：

1
2// Call query order API
3public function queryOrder($instance)
4{
5    try {
6        $resp = $instance
7            ->v3->global->transactions->outTradeNo->_out_trade_no_
8            ->get([
9                    'query' => [
10                'sp_mchid'     => '1900000000',
11                'sub_mchid'    => '100012321',
12                    ],
13                    'out_trade_no' => 'YX0001'
14                ]
15            );
16
17        echo $resp->getStatusCode(), PHP_EOL;
18        echo $resp->getBody(), PHP_EOL;
19    } catch (Exception $e) {
20        // Exception handling
21	}
22}

重要参数：

id：微信支付订单号

out_trade_no：商户内部订单号

可以用上述任一订单号进行查询。其他重要参数请前往查询订单API文档页面参考。

3.2.3 申请退款

步骤说明：支付完成支付状态为SUCCESS后，可以调用该接口提交退款请求。

代码示例 - JAVA：

1
2    @Test
3    //Call Refund API
4    public void refundTest() throws IOException {
5		String refundBody = String.join("\n" ,
6                		"{" ,
7                        "'sp_appid': 'wx2421b1c4370ec43b', " ,
8                        "'sp_mchid': '10000100'," ,
9                        "'sub_mchid': '20000100'," ,
10                        "'transaction_id': '1008450740201411110005820873'," ,
11                        "'out_refund_no': 'R20150806125346'," ,
12                        "    'amount' : {" ,
13                        "        'refund': 5," ,
14                        "        'total':10," ,
15                        "         'currency':'HKD'" ,
16                        "    }," ,
17                        "    'reason': 'The item has been sold out.'," ,
18                        "    'source': 'REFUND_SOURCE_UNSETTLED_FUNDS'" ,
19                        "}").replace("'","\"");
20        HttpPost httpPost = new HttpPost("https://apihk.mch.weixin.qq.com/v3/global/refunds");
21        httpPost.addHeader("Accept", "application/json");
22        httpPost.addHeader("Content-type", "application/json; charset=utf-8");
23        httpPost.setEntity(new StringEntity(refundBody));
24        CloseableHttpResponse response = httpClient.execute(httpPost);
25        //Process the response 
26    }
27

示例代码 - GO：

1
2func refund() {
3   refundRequestBody := `{
4    "sp_appid": "wx2421b1c4370ec43b",
5    "sp_mchid": "10000100",
6    "sub_mchid": "20000100",
7    "transaction_id": "1008450740201411110005820873",
8    "out_refund_no": "R20150806125346",
9    "amount" : {
10        "refund": 50,
11        "total":100,
12         "currency":"HKD"
13    },
14    "reason": "The item has been sold out",
15    "source": "REFUND_SOURCE_UNSETTLED_FUNDS"
16}`
17   result, err := client.Post(ctx, "https://apihk.mch.weixin.qq.com/v3/global/refunds", refundRequestBody)
18   if err != nil {
19      // Process error
20   }
21   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
22}

示例代码 - PHP：

1
2// Call Refund API
3public function refundOrder($instance){
4    try {
5        $resp = $instance
6            ->chain('v3/global/refunds')
7            ->post(['json' => [
8                'sp_appid'     => 'wxdace12300000000',
9                'sp_mchid'     => '1900000000',
10                'sub_mchid'    => '100012321',
11                'out_trade_no' => 'YX0001',
12                "out_refund_no"=> "REFUNDYX0001",
13                'amount'       => [
14                    'refund'   => 1,
15                    'total'    => 1,
16                    'currency' => 'USD'
17                ]
18            ]]);
19        echo $resp->getStatusCode(), PHP_EOL;
20        echo $resp->getBody(), PHP_EOL;
21    } catch (Exception $e) {
22        // Exception handling
23    }
24}

重要参数：

out_trade_no: 商户内部订单号

transaction_id: 微信订单号

out_refund_no: 商户内部退款单号，应与订单号一一对应

notify_url: 退款结果接收地址

其他重要参数请前往申请退款API文档页面参考。

3.2.4 查询单笔退款

步骤说明：提交退款申请后，通过调用该接口查询退款状态。

代码示例 - JAVA：

1
2    @Test
3    //Call Query Refund API
4    public void querySingleRefundTest() throws IOException {
5        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/refunds/out-refund-no/RYX001?sub_mchid=100012321&sp_mchid=1900000000");
6        httpGet.addHeader("Accept", "application/json");
7        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
8        CloseableHttpResponse response = httpClient.execute(httpGet);
9        //Process the response 
10    }
11

示例代码 - GO：

1
2//Query single refund API
3func querySingleRefund() {
4   result, err := client.Get(ctx, "https://apihk.mch.weixin.qq.com/v3/global/refunds/out-refund-no/REFUNDYX001?sub_mchid=100012321&sp_mchid=1900000000")
5   if err != nil {
6      // Process error
7   }
8   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
9}

示例代码 - PHP：

1
2// Call Query Refund API
3public function queryRefund($instance){
4    try {
5        $resp = $instance
6            ->v3->global->refunds->outRefundNo->_out_refund_no_
7            ->get([
8                'query' => [
9                    'sp_mchid' => '1900000000',
10                    'sub_mchid'=> '100012321'
11                ],
12                'out_refund_no' => 'REFUNDYX0001'
13            ]);
14
15        echo $resp->getStatusCode(), PHP_EOL;
16        echo $resp->getBody(), PHP_EOL;
17    } catch (Exception $e) {
18        // Exception handling
19    }
20}

重要参数：

out_trade_no: 商户内部订单号

refund_id：微信支付退款单号

其他重要参数请前往查询单笔退款API文档页面参考。

3.2.5 查询所有退款

步骤说明：提交退款申请后，通过调用该接口查询一笔订单下对应的全部退款信息。

代码示例 - JAVA：

1
2    @Test
3    //Call Query All Refund API
4    public void queryAllRefundTest() throws IOException {
5        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/refunds" +
6                "?out_trade_no=YX202111100020&count=10&offset=0&sp_mchid=1900000000&sub_mchid=100012321");
7        httpGet.addHeader("Accept", "application/json");
8        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
9        CloseableHttpResponse response = httpClient.execute(httpGet);
10        //Process the response 
11    }
12

示例代码 - GO：

1
2//Query all refund API
3func queryAllRefund() {
4   result, err := client.Get(ctx, "https://apihk.mch.weixin.qq.com/v3/global/refunds/out-refund-no/out_trade_no=YX001&count=10&offset=0&sp_mchid=1900000000&sub_mchid=100012321")
5   if err != nil {
6      // Process error
7   }
8   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
9}

示例代码 - PHP：

1
2// Call Query All Refund API
3public function queryAllRefund($instance){
4    try {
5        $resp = $instance
6            ->v3->global->refunds
7            ->get([
8                'query' => [
9                    'out_trade_no' => 'YX001',
10                    'count' => 10,
11                    'offset' => 0,
12                    'sp_mchid' => '1900000000',
13                    'sub_mchid'=> '100012321'
14                ]
15            ]);
16
17        echo $resp->getStatusCode(), PHP_EOL;
18        echo $resp->getBody(), PHP_EOL;
19    } catch (Exception $e) {
20        // Exception handling
21    }
22}

重要参数：

out_trade_no: 商户内部订单号

transaction_id: 微信订单号

offset: 分页起始位置

count: 单页返回的记录数，最大20条记录.

其他重要参数请前往查询所有退款API文档页面参考。

3.2.6 下载对账单

步骤说明：商户每天可以通过调用该接口可以下载历史交易账单，通过对帐单核对后可以校对更正支付信息。

代码示例 - JAVA：

1
2    @Test
3    //Downloading Reconciliation API
4    public void downloadReconTest() throws IOException {
5        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/statements?date=20220401&mchid=1900000000");
6        httpGet.addHeader("Accept", "application/json");
7        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
8        CloseableHttpResponse response = httpClient.execute(httpGet);
9        //Process the response 
10    }
11

示例代码 - GO：

1
2//Download recon file API
3func downloadReconFile() {
4   result, err := client.Get(ctx, "https://apihk.mch.weixin.qq.com/v3/global/statements?date=20220401&mchid=1900000000")
5   if err != nil {
6      // Process error
7   }
8   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
9}

示例代码 - PHP：

1
2//Downloading Reconciliation API
3public function downloadReconFile($instance){
4    try {
5        $resp = $instance
6            ->v3->global->statements
7            ->get([
8                'query' => [
9                    'date' => '20220401',
10                    'mchid' => '1900000000'
11                ]
12            ]);
13
14        echo $resp->getStatusCode(), PHP_EOL;
15        echo $resp->getBody(), PHP_EOL;
16    } catch (Exception $e) {
17        // Exception handling
18    }
19}

重要参数：

date: 账单日期, 格式：20180103

其他重要参数请前往下载对账单API文档页面参考。

3.2.7 关闭订单

步骤说明：下单超过5分钟后，可以调用该接口对下单未支付的订单进行关单操作，以便商户更换订单号重新下单发起支付或商户系统退出不再受理后避免用户继续支付。

代码示例 - JAVA：

1
2    @Test
3    //Call close order API
4    public void closeOrderTest() throws IOException {
5		String closeBody = String.join("\n" ,
6                		"{" ,
7                        "    'sp_mchid': '10000100'," ,
8                        "    'sub_mchid': '20000100'" ,
9                        "}").replace("'","\"");
10        HttpPost httpPost = new HttpPost("https://apihk.mch.weixin.qq.com/v3/global/transactions/out-trade-no/YX001/close");
11        httpPost.addHeader("Accept", "application/json");
12        httpPost.addHeader("Content-type", "application/json; charset=utf-8");
13        httpPost.setEntity(new StringEntity(closeBody));
14        CloseableHttpResponse response = httpClient.execute(httpPost);
15        System.out.println(response.getStatusLine().getStatusCode());
16    }
17

示例代码 - GO：

1
2//Call close order API
3func closeOrder() {
4   closeOrderBody := `{
5    "sp_mchid": "10000100",
6    "sub_mchid": "20000100"
7   }`
8   result, err := client.Post(ctx, "https://apihk.mch.weixin.qq.com/v3/global/transactions/out-trade-no/YX001/close", closeOrderBody)
9   if err != nil {
10      // Process error
11   }
12   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
13}

示例代码 - PHP：

1// Call close order API
2public function closeOrder($instance){
3    try {
4        $resp = $instance
5            ->v3->global->transactions->outTradeNo->_out_trade_no_->close
6            ->post([
7                'json' => [
8                'sp_mchid'     => '10000100',
9                'sub_mchid'    => '20000100'
10                ],
11                'out_trade_no' => 'YX0001'
12            ]);
13        echo $resp->getStatusCode(), PHP_EOL;
14        echo $resp->getBody(), PHP_EOL;
15    } catch (Exception $e) {
16        // Exception handling
17    }
18}

重要参数：

out_trade_no: 商户内部订单号

transaction_id: 微信支付订单号

可以用上述任一订单号进行查询。其他重要参数请前往关闭订单API文档页面参考。

3.2.8 下载平台证书

步骤说明：在调用其他接口之前，需要调用该接口下载平台证书用于对返回消息进行验签和返回消息中的加密字段进行解密。

代码示例 - JAVA

1
2    @Test
3    //Call certificate downloading API
4    public void certDownloadingTest() throws IOException {
5        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/certificates");
6        httpGet.addHeader("Accept", "application/json");
7        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
8
9        CloseableHttpResponse response = httpClient.execute(httpGet);
10        //Process the response 
11//Get the response body: EntityUtils.toString(response.getEntity());
12//Get the response status code: response.getStatusLine().getStatusCode();
13
14        //Instead of calling the API to download platform certificate，
15        //We also recommend use the certificateMenager to get the valid certificate
16        verifier.getValidCertificate();
17    }
18

示例代码 - GO：

1
2//Calling download certificate API
3func downloadCert() {
4   result, err := client.Get((ctx, "https://apihk.mch.weixin.qq.com/v3/global/certificates"))
5   if err != nil {
6      if core.IsAPIError(err, "INVALID_REQUEST") {
7         //Process invalid request
8      }
9      // Process other error
10   }
11   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
12}

示例代码 - PHP：

1
2// Call download certificate API
3public function downloadCert($instance){
4    $resp = $instance->chain('v3/global/certificates')->get(
5        ['debug' => true] // debug mode，https://docs.guzzlephp.org/en/stable/request-options.html#debug
6    );
7    echo $resp->getBody(), PHP_EOL;
8}

重要参数：无

其他重要参数请前往下载平台证书API文档页面参考。

3.2.9 支付结果通知

步骤说明：用户完成支付后，微信支付会向下单时传入的notify_url推送支付结果通知，商户需要在接收到通知后返回对应的信息。

注意

同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
如果在所有通知频率(4小时)后没有收到微信侧回调，商户应调用查询订单接口确认订单状态。

特别提醒：机构系统对于支付结果通知的内容一定要做签名验证,并校验返回的订单金额是否与商户侧的订单金额一致，防止数据泄露导致出现“假通知”，造成资金损失。

3.2.9.1 通知规则

用户支付完成后，微信会把相关支付结果和用户信息发送给商户，商户需要接收处理后返回应答成功。只有支付成功才会通知。

对后台通知交互时，如果微信收到应答不是成功或超时，微信认为通知失败，微信会通过一定的策略定期重新发起通知，尽可能提高通知的成功率，但微信不保证通知最终能成功。（通知频率为15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - 总计 24h4m）

3.2.9.2 通知报文

支付结果通知是以“POST”方法访问商户设置的通知url，通知的数据以“JSON”格式通过请求主体（BODY）传输。通知的数据包括了加密的支付结果详情。

下面详细描述证书解密的流程

1、从商户平台上获取商户的密钥，记为“key”。

2、针对“algorithm”中描述的算法（目前为AEAD_AES_256_GCM），取得对应的参数“nonce”和“associated_data”。

3、使用“key”、“nonce”和“associated_data”对数据密文“ciphertext”进行解密（需要先对ciphertext做base64解码，然后再解密），得到证书内容

注意

AEAD_AES_256_GCM算法的接口细节，请参考rfc5116。微信支付使用的密钥key长度为32个字节，随机串nonce长度12个字节，associated_data长度小于16个字节并可能为空。

3.2.9.3 通知签名

加密不能保证通知请求来自微信。微信会对发送给商户的通知进行签名，并将签名值放在通知的HTTP头Wechatpay-Signature。商户应当验证签名，以确认请求来自微信，而不是其他的第三方。签名验证的算法请参考《微信支付API V3签名验证》。

3.2.9.4 回调示例

支付成功结果通知

1
2{
3    "id":"EV-2018022511223320873",
4    "create_time":"20180225112233",
5    "resource_type":"encrypt-resource",
6    "event_type":"TRANSACTION.SUCCESS",
7    "resource" : {
8        "algorithm":"AEAD_AES_256_GCM",
9        "ciphertext": "...",
10        "nonce": "...",
11        "associated_data": ""
12    }
13}
14

商户对resource对象进行解密后，得到的资源对象示例

1
2{
3    "id": "1008450740201411110005820873",
4    "sp_appid": "wx2421b1c4370ec43b",
5    "sp_mchid": "10000100",
6    "sub_mchid": "20000100",
7    "out_trade_no": "20150806125346",
8    "payer": {
9      "sp_openid": "oUpF8uN95-Ptaags6E_roPHg7AG0"
10    },
11    "amount" : {
12        "total": 528800,
13        "currency": "HKD",
14        "payer_total": 518799,
15        "payer_currency": "CNY",
16        "exchange_rate" : {
17            "type": "SETTLEMENT_RATE",
18            "rate": 8000000
19        }
20    },
21    "trade_type": "MICROPAY",
22    "trade_state": "SUCCESS",
23    "trade_state_desc": "支付成功",
24    "bank_type": "CCB_DEBIT",
25    "attach": "支付测试",
26    "success_time": "2018-06-08T10:34:56+08:00",
27    "promotion_detail":[
28        {
29            "promotion_id":"109519",
30            "name":"单品惠-6",
31            "scope":"SINGLE",
32            "type":"DISCOUNT",
33            "amount":1,
34            "currency":"HKD",
35            "activity_id":"931386",
36            "wechatpay_contribute_amount":1,
37            "merchant_contribute_amount":0,
38            "other_contribute_amount":0,
39            "goods_detail":[
40                {
41                    "goods_id":"iphone6s_16G",
42                    "goods_remark":"商品备注",
43                    "quantity":1,
44                    "price":528800
45                }
46            ]
47        }
48    ]
49}
50

3.2.9.5 通知应答

支付通知http应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx。

注意

当商户后台应答失败时，微信支付将记录下应答的报文，建议商户按照以下格式返回。

其他重要参数请前往支付结果通知API文档页面参考。

3.2.10 退款通知

步骤说明：退款状态改变后，微信会把相关退款结果发送给商户。

注意

同样的通知可能会多次发送给商户系统。商户系统必须能够正确处理重复的通知。推荐的做法是，当商户系统收到通知进行处理时，先检查对应业务数据的状态，并判断该通知是否已经处理。如果未处理，则再进行处理；如果已处理，则直接返回结果成功。在对业务数据进行状态检查和处理之前，要采用数据锁进行并发控制，以避免函数重入造成的数据混乱。
如果在所有通知频率(4小时)后没有收到微信侧回调，商户应调用查询订单接口确认订单状态。

3.2.10.1 通知规则

退款状态改变后，微信会把相关退款结果发送给商户。

3.2.10.2 通知报文

退款结果通知是以“POST”方法访问商户设置的通知url，通知的数据以“JSON”格式通过请求主体（BODY）传输。通知的数据包括了加密的退款结果详情。

下面详细描述证书解密的流程

1、从商户平台上获取商户的密钥，记为“key”。

2、针对“algorithm”中描述的算法（目前为AEAD_AES_256_GCM），取得对应的参数“nonce”和“associated_data”。

3、使用“key”、“nonce”和“associated_data”对数据密文“ciphertext”进行解密（需要先对ciphertext做base64解码，然后再解密），得到证书内容

注意

3.2.10.3 通知签名

3.2.10.4 回调示例

退款通知

1
2{
3	"id": "EV-2018022511223320873",
4	"create_time": "2018-06-08T10:34:56+08:00",
5	"resource_type": "encrypt-resource",
6	"event_type": "REFUND.SUCCESS",
7	"summary": "退款成功",
8	"resource": {
9		"original_type": "refund",
10		"algorithm": "AEAD_AES_256_GCM",
11		"ciphertext": "...",
12		"associated_data": "",
13		"nonce": "..."
14	}
15}
16

商户对resource对象进行解密后，得到的资源对象示例

1
2{
3    "sp_mchid": "1900000100",
4    "sub_mchid": "1900000109",
5    "transaction_id": "1008450740201411110005820873",
6    "out_trade_no": "20150806125346",
7    "refund_id": "50200207182018070300011301001",
8    "out_refund_no": "7752501201407033233368018",
9    "refund_status": "SUCCESS",
10    "success_time": "2018-06-08T10:34:56+08:00",
11    "recv_account": "招商银行信用卡0403",
12    "fund_source": "REFUND_SOURCE_UNSETTLED_FUNDS",
13    "amount" : {
14        "total": 528800,
15        "currency": "HKD",
16        "refund": 528800,
17        "payer_total": 528800,
18        "payer_refund": 528800,
19        "payer_currency": "HKD",
20        "exchange_rate" : {
21            "type": "SETTLEMENT_RATE",
22            "rate": 100000000
23        }
24    }
25}
26

3.2.10.5 通知应答

退款通知http应答码为200或204才会当作正常接收，当回调处理异常时，应答的HTTP状态码应为500，或者4xx。

注意

当商户后台应答失败时，微信支付将记录下应答的报文，建议商户按照以下格式返回。

其他重要参数请前往退款通知API文档页面参考。

3.2.11 查询资金结算明细

步骤说明：商户在交易完结之后，可按结算日期查询已结算资金明细（sette_state为SETTLED），也可以查询未结算资金明细（sette_state为UNSETTLE）。

注意

该接口供跨境收单机构/直连商户使用，特别是，日本/澳门机构商户若开通香港钱包业务，需要对接该接口。

代码示例 - JAVA：

1
2    @Test
3    //Query Settlement API
4    public void querySettlementTest() throws IOException {
5        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/settle/settlements" +
6                "?sub_mchid=100012321&settle_state=SETTLED&settle_start_date=20221225" +
7                "&settle_end_date=20221226&offset=10&limit=5");
8        httpGet.addHeader("Accept", "application/json");
9        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
10        CloseableHttpResponse response = httpClient.execute(httpGet);
11        //Process the response 
12    }
13

示例代码 - GO：

1
2//Query settlement API
3func querySettlement() {
4   result, err := client.Get(ctx, "https://apihk.mch.weixin.qq.com/v3/global/settle/settlements?sub_mchid=100012321&settle_state=SETTLED&settle_start_date=20221225&settle_end_date=20221226&offset=10&limit=5")
5   if err != nil {
6      // Process error
7   }
8   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
9}

示例代码 - PHP：

1
2//Querying Settlement Info API
3public function querySettlementInfo($instance){
4    try {
5        $resp = $instance
6            ->v3->global->settle->settlements
7            ->get(['query' => [
8                'sub_mchid' => '100012321',
9                'settle_state' => 'SETTLED',
10                'settle_start_date' => '20221225',
11                'settle_end_date' => '20221226',
12                'offset' => '10',
13                'limit' => '5'
14            ]]);
15
16        echo $resp->getStatusCode(), PHP_EOL;
17        echo $resp->getBody(), PHP_EOL;
18    } catch (\Exception $e) {
19        // Exception handling
20    }
21}

重要参数：

settle_state：资金结算状态，枚举值：

SETTLED：已结算

UNSETTLE：未结算

其他重要参数请前往查询资金结算明细API文档页面参考。