Development Guidelines

Update Time：2025.03.24

1. API Rules

In order to provide a simple, consistent and easy-to-use development experience to merchants while ensuring payment security, we have launched the latest WeChat Pay APIv3 interface. Please refer to “APIv3 Interface Rules” for the specific rules of this API version.

2. Development Environment Setup

To help developers call the open interface, the development libraries of Java、PHP、GO are provided, encapsulating the basic functions such as signature generation, signature verification, encryption/decryption of sensitive information, and media document upload

JAVA

2.1.1. Conditions of Use

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. Installation

Gradle：Add the following dependencies to your build.gradle document

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

Maven：Add the following dependencies to the pom.xml document

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. Initialization

Initialize WechatPayHttpClientBuilder to create an httpClient, which will be used to send requests to call the WeChatPay interface. Initialize a verifier instance with CertificatesManager to verify the signature.

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

2.1.4. General Functions

Encrypting Sensitive Information

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

Decrypting Sensitive Information

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

Golang

2.2.1. Conditions of Use

WechatPay merchant account
GO SDK 0.2.13 or later version

2.2.2. Installation

1、Manage your projects with Go Modules

If Go Modules are not used for the dependency management of your projects, run in the project root directory:

go mod init

2、Without cloning the code in the repository, run directly in the project directory:

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

to add a dependency, modify modand download SDK

2.2.3. Initialization

Initialize Client and load the merchant account, private key, API V3 key, merchant certificate and serial number to Client for sending an interface request later.

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

2.2.4. General Functions

Encrypting Sensitive Information

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   // Encrypt the certificate by OAEP padding
9   ciphertext, _ := EncryptOAEPWithCertificate(message, testRSACryptoUtilCertificate)
10   
11  // Encrypt the certificate by PKCS1 padding
12   ciphertext, _ := EncryptPKCS1v15WithCertificate(message, testRSACryptoUtilCertificate)
13}
14

Decrypting Sensitive Information

1
2func TestDecryption(t *testing.T) {
3	var testRSACryptoUtilPrivateKeyStr = `-----BEGIN PRIVATE KEY-----
4-----END PRIVATE KEY-----`
5	testRSACryptoUtilPrivateKey, _ = LoadPrivateKey(testingKey(testRSACryptoUtilPrivateKeyStr))
6	const ciphertext = ""
7
8	// Decrypt the private key by PKCS1 padding
9	decryptMessage, _ := DecryptPKCS1v15(ciphertext, testRSACryptoUtilPrivateKey)
10
11	// Decrypt the private key by OAEP padding
12	decryptMessage, _ := DecryptOAEP(ciphertext, testRSACryptoUtilPrivateKey)
13}

PHP

2.3.1. Conditions of Use

Guzzle 7.0，PHP >= 7.2.5
Guzzle 6.5，PHP >= 7.1.2
PHP 8 is supported.

2.3.2. Installation

It is recommended to use the PHP package management tool Composer to install SDK:

composer require wechatpay/wechatpay

2.3.3. Initialization

Initialize Client and load the merchant account, private key, API V3 key, merchant certificate and serial number to Client in order to send an interface request later.

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. General Functions

Encrypting Sensitive Information

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

Decrypting Sensitive Information

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

3. Fast Access

3.1. Business Sequence Chart

Password-free payment:

Password-based payment:

3.2. Example of API access

The document shows how to use the WeChat Pay server SDK to quickly pay by scanning code and interface with WeChat Pay.

Notice

The code examples in the document illustrate the basic usage of API. Before running the code, the example parameters in the code need to be replaced with the merchant's own account and request parameters.
The access steps below are for your information, and should be evaluated and modified according to the merchant’s own business demands.

3.2.1 Payment request

Procedure: Submit a WeChat payment code to pay for the order through this API. Scan the user's payment code to call this feature.

Code example-JAVA:

1
2    @Test
3    //Call Quick Pay Order API
4    public void quickPayOrderTest() throws IOException {
5		String requestBody = String.join("\n" ,
6                		"{" ,
7                        "'sp_appid': 'wxdace645e0bc2c424'," ,
8                        "'sp_mchid': '10000100'," ,
9                        "'sub_mchid': '20000100'," ,
10                        "'out_trade_no': '20150806125346'," ,
11                        "'merchant_category_code': '4111'," ,
12                        "'payer': {" ,
13                        "'auth_code': '134650720866361395'" ,
14                        "}," ,
15                        "'trade_type': 'MICROPAY'," ,
16                        "'amount': {" ,
17                        "'total': 1," ,
18                        "'currency': 'HKD'" ,
19                        "}," ,
20                        "'attach': 'Payment Test'," ,
21                        "'description': 'Image Store - Tencent Building in Shenzhen - QQ Doll'," ,
22                        "'goods_tag': '1234'," ,
23                        "'limit_pay': 'no_credit'," ,
24                        "'detail': {" ,
25                        "'cost_price': 1," ,
26                        "'receipt_id': '1234'," ,
27                        "'goods_detail': [{" ,
28                        "'goods_id': 'iphone6s_16G'," ,
29                        "'wxpay_goods_id': '3405'," ,
30                        "'goods_name': 'iPhone6s 16G'," ,
31                        "'quantity': 1," ,
32                        "'price': 1" ,
33                        "}]" ,
34                        "}," ,
35                        "'scene_info': {" ,
36                        "'payer_client_ip': '14.23.150.211'," ,
37                        "'device_ip': '59.37.125.32'," ,
38                        "'device_id': '013467007045764'," ,
39                        "'operator_id': 'P001'," ,
40                        "'store_info': {" ,
41                        "'id': 'SZTX001'," ,
42                        "'name': 'Tencent Building Branch'," ,
43                        "'address': 'Nanshan District, Shenzhen, Guangdong'" ,
44                        "}" ,
45                        "}" ,
46                        "}").replace("'","\"");
47        HttpPost httpPost = new HttpPost("https://apihk.mch.weixin.qq.com/v3/global/micropay/transactions/pay");
48        httpPost.addHeader("Accept", "application/json");
49        httpPost.addHeader("Content-type", "application/json; charset=utf-8");
50        httpPost.setEntity(new StringEntity(requestBody));
51        CloseableHttpResponse response = httpClient.execute(httpPost);
52        //Process the response 
53    }
54
55

Code example-Go:

1
2func quickPayOrder() {
3   requestBody := `{
4	"sp_appid": "wxdace645e0bc2c424",
5	"sp_mchid": "10000100",
6	"sub_mchid": "20000100",
7	"out_trade_no": "20150806125346",
8	"merchant_category_code": "4111",
9	"payer": {
10		"auth_code": "134650720866361395"
11	},
12	"trade_type": "MICROPAY",
13	"amount": {
14		"total": 1,
15		"currency": "HKD"
16	},
17	"attach": "Payment Test",
18	"description": "Image Store - Tencent Building in Shenzhen - QQ Doll",
19	"goods_tag": "1234",
20	"limit_pay": "no_credit",
21	"detail": {
22		"cost_price": 1,
23		"receipt_id": "1234",
24		"goods_detail": [{
25			"goods_id": "iphone6s_16G",
26			"wxpay_goods_id": "3405",
27			"goods_name": "iPhone6s 16G",
28			"quantity": 1,
29			"price": 1
30		}]
31	},
32	"scene_info": {
33		"payer_client_ip": "14.23.150.211",
34		"device_ip": "59.37.125.32",
35		"device_id": "013467007045764",
36		"operator_id": "P001",
37		"store_info": {
38			"id": "SZTX001",
39			"name": "Tencent Building Branch",
40			"address": "Nanshan District, Shenzhen, Guangdong"
41		}
42	}
43}`
44   result, err := client.Post(ctx, "https://apihk.mch.weixin.qq.com/v3/global/micropay/transactions/pay", requestBody)
45   if err != nil {
46      // Process error
47   }
48   log.Printf("status=%d resp=%s", result.Response.StatusCode, result.Response.Body)
49}

Code example-PHP:

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

Critical parameters:

out_trade_no: Internal order ID in merchant’s system

auth_code: Scan the payment authorization code, i.e., the digits corresponding to the payment displayed in the WeChat Wallet

Please refer to the API document for ordering by scanning code for other critical parameters.

3.2.2 Query

Procedure: The merchant is required to take the initiative to check the order status after placing an order for a certain period of time.

Code example-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

Code example-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}

Code example-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}

Critical parameters:

id: WeChat payment order ID

out_trade_no: internal order ID in merchant’s system

Query with any order ID above. Please refer to the API document for ordering by scanning code for other critical parameters.

3.2.3 Refund

Procedure: After the payment is completed and the payment status is SUCCESS, call this interface to submit a refund request.

Code example-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

Code example-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}

Code example-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}

Critical parameters:

out_trade_no: internal order ID in merchant’s system

transaction_id: WeChat order ID

out_refund_no: internal refund No. in merchant’s system, which should correspond to order ID

notify_url: address for receiving refund results

Please refer to the API document for ordering by scanning code for other critical parameters.

3.2.4 Query one refund

Procedure: After submitting a refund request, query the refund status by calling this interface.

Code example-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

Code example-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}

Code example-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}

Critical parameters:

out_trade_no: internal refund No. in merchant’s system

refund_id：WeChat payment refund order ID

Please refer to the API document for ordering by scanning code for other critical parameters.

3.2.5 Query all refunds

Procedure: After submitting a refund request, query all refund information corresponding to one payment order.

Code example-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

Code example-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}

Code example-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}

Critical parameters:

out_trade_no: Internal order ID in merchant’s system

transaction_id: WeChat order ID

offset: Start position of paging

count: Number of records returned in a single page, up to 20 records.

Please refer to the API document for ordering by scanning code for other critical parameters.

3.2.6 Download statement of account

Procedure: Merchants can download the historical transaction statements by calling this interface on a daily basis, and correct the payment information by reconciling the statements.

Code example-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

Code example-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}

Code example-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}

Critical parameters:

date: Statement date, format: 20180103

Please refer to the API document for ordering by scanning code for other critical parameters.

3.2.7 Cancel an order

Procedure: Call the payment interface to cancel the order after minimum 15 seconds. If the user fails to pay for this order, the WeChat payment system will close the order; otherwise, the WeChat payment system will refund the order to the user.

Code example-JAVA:

1
2    @Test
3    //Call revoke order API
4    public void RevokeOrderTest() throws IOException {
5		String revokeBody = 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/micropay/transactions/out-trade-no/YX001/reverse");
11        httpPost.addHeader("Accept", "application/json");
12        httpPost.addHeader("Content-type", "application/json; charset=utf-8");
13        httpPost.setEntity(new StringEntity(revokeBody));
14        CloseableHttpResponse response = httpClient.execute(httpPost);
15        //Process the response 
16    }
17

Code example-Go:

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

Code example-PHP:

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

Critical parameters:

out_trade_no: WeChat payment order ID

transaction_id: internal order ID in merchant’s system

Please refer to the API document for ordering by scanning code for other critical parameters.

3.2.8 Download platform certificate

Procedure: Before calling other interfaces, call this interface to download the platform certificate to verify the signature of the returned message and decrypt the encrypted fields therein.

Code example-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

Code example-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}

Code example-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}

Critical parameters: None

Please refer to the API document for ordering by scanning code for other critical parameters.

3.2.9 Refund notification

Procedure: After the user makes the payment, WeChat Pay will push the payment result notification to the notify_url introduced while placing the order, and the merchant needs to feed back accordingly after receiving the notification.

Notes:

The same notification may be sent to the merchant system multiple times. The merchant system must be able to process duplicate notifications properly. It is recommended to first check the status of the corresponding business data when receiving a notification for processing, and determine whether the notification has been processed. If not, the notification should be processed; if it has been processed, the success result should be returned. Before status checking and processing of the business data, a data lock should be used to implement concurrency control and avoid data confusion caused by function reentry.
If no callback is received from WeChat side after all notification frequencies (4 hours), the merchant shall call the Query Order interface to confirm the order status.

Special reminder: The merchant system must perform signature verification for the content of the notification of payment results, and verify whether the returned order amount is consistent with that of the merchant side, thus preventing any "false notification" and even capital loss caused by data leakage.

3.2.9.1 Notification Rules

In case of any refund status changes, WeChat will send the related refund results to the merchant.

When interacting with the background notification, if the response received by WeChat from the merchant is not success or timed out, WeChat thinks the notification fails. WeChat will periodically resend the notification according to the specified policy to maximize the success rate of the notification, but WeChat does not guarantee final success of the notification. ((Notification frequency is 15s/15s/30s/3m/10m/20m/30m/30m/30m/60m/3h/3h/3h/6h/6h - total 24h and 4m))

3.2.9.2 Notification Message

The deduction result notification accesses the notification URL set by the merchant using the POST method, and the notification data is transmitted through the request body (BODY) in the JSON format. The data in the notification includes the details about the encrypted refund result.

The certificate decryption process is detailed as follows

1、Obtain the merchant's key from the merchant platform, and record it as “key”.

2、Get the corresponding parameters “nonce” and “associated_data” for the algorithm described in “algorithm” (currently AEAD_AES_256_GCM).

3、Decrypt “ciphertext” with “key”, “nonce” and “associated_data” (perfomr base64 decoding for ciphertext first, and then decrypt it) to obtain the certificate content

Notice

For the interface details of the AEAD_AES_256_GCM algorithm, please refer to rfc5116. The length of the key used in Wechat Pay is 32 bytes, the length of the random string nonce is 12 bytes, and the length of associated_data is less than 16 bytes and may be empty.

3.2.9.3 Notification Signature

Encryption does not guarantee that the notification requests come from WeChat. WeChat will sign the notification sent to the merchant and put the signature value in the HTTP header Wechatpay-Signature of the notification. Merchants should verify the signature to confirm that the request comes from WeChat, and not any other third parties. For the signature verification algorithm, please refer to WeChat Pay API V3 Signature Verification.

3.2.9.4 Callback Example

Notification of Refund Result

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

An example of the resource object obtained after the merchant decrypts the resource object

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.9.5 Notification Response

The http response code of the refund notification should be either 200 or 204 for normal receipt. In case of any callback processing error, the HTTP status code of the response should be 500 or 4xx.

Note:

When the merchant background returns the failure response to Weixin Pay, Weixin Pay will record the response message. It is recommended that the merchant return the message in the following format.

Please refer to the API document for ordering by scanning code for other critical parameters.

3.2.10 API for querying fund settlement details

Procedure: After transactions are completed, the merchant can query the settled fund details (sette_state is SETTLED) or the unsettled fund details (sette_state is UNSETTLE) by settlement date.

Note:

This API is designed for the cross-border acquiring institutions/direct merchants. In particular, if institutions/merchants in Japan and Macao have enabled Hong Kong Wallet services, they need to connect this API.

Code example-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

Code example-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}

Code example-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}

Critical parameters:

settle_state： Fund settlement status, enumeration value:

SETTLED：settled

UNSETTLE：not settled

Please refer to the API document for ordering by scanning code for other critical parameters.