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

After an institution submits a sub-merchant onboarding request, WeChat Pay will perform a systematic review of the sub-merchant information and return a status to show whether the request is successful or further manual review is required. Institutions shall pay attention to the results returned by the interface:

Response for successful onboarding

1
2{
3	"sub_mchid": "20000100",
4	"verification_status": "Approved"
5}
6
7

Response for failed onboarding

1
2{
3  "code": "INVALID_REQUEST",
4  "message": "Parameter format verification error",
5  "detail": {
6    "field": "#/properties/payer",
7    "value": "1346177081915535577",
8    "issue": "Does not match the ALLOF schema",
9    "location": "body"
10  }
11}
12

Response when onboarding requires further manual review

1
2{
3  "sub_mchid": "20000100",
4  "verification_status": "Under Review",
5  "description": "This merchant takes effect only after being approved. Please check the verification status on WeChat Pay Merchant Platform."
6}
7

Take note that at this point of time, the sub-merchants do not have payment authorization and cannot initiate any transaction. They can only initiate a transaction when they have passed the sub-merchant review. An institution can query sub-merchant's status in the sub-merchant query interface.

Query sub-merchant's status

After an institution has submitted a sub-merchant onboarding request, the institution can use the query interface to query the sub-merchant's status:

OPERATING: Normal; the sub-merchant has passed the review and onboarding is complete. The sub-merchant has normal payment authorization and can initiate transactions.

DEACTIVATED: The sub-merchanthas been deactivated; the institution has suspended the sub-merchant account after onboarding application is approved and the sub-merchant has no payment authorization and cannot initiate any transaction.

CLOSED: The sub-merchant has been closed; after the sub-merchant has passed the onboarding review, WeChat Pay has disabled payment authorization and the sub-merchant cannot initiate any transaction.

INCOMPLETE_APPLICATION: Onboarding process is incomplete; the sub-merchant's onboarding application is incomplete and has no payment authorization and cannot initiate any transaction. Please check the onboarding application status in the application_status field.

PENDING: Pending; after the sub-merchant's onboarding application is approved, the sub-merchant's information has not passed the regular review and the institution is required to log in to the WeChat Pay merchant platform to check and process it. The sub-merchant has normal payment authorization and can initiate transactions.

What to do when sub-merchant has not completed the onboarding review

If the query result shows that the sub-merchant's status is "INCOMPLETE_APPLICATION", check the application status in the application_status field:

UNDER_REVIEW: Application is currently under review; a WeChat Pay reviewer is reviewing the sub-merchant's onboarding application. Please wait and check again one day later. If the status remains as "UNDER_REVIEW" after 7 working days, contact WeChat Pay for query.

REJECTED: It has been rejected; the sub-merchant's onboarding application has been rejected by WeChat Pay and the institution must log in to the WeChat Pay merchant platform and resubmit the application after amending the information (please check the reason for rejection in the application_rejected_detail field)

3.2. Example of API access

The document shows how to use the WeChat Pay server SDK to In-App Payment 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 Inbound sub-merchant

Procedure: The merchant submits the sub-merchant data, and WeChat Pay will create a sub-merchant account for each sub-merchant.

Fields of sensitive information: For the parameters that contain sensitive information such as contact information, WeChat adds the “field encryption” security mechanism to ensure that the sensitive information can be seen by the data recipient only.

Encryption method:

Obtain the Weixin Pay Platform certificate and the corresponding platform certificate serial number, Obtain WeChat Pay Platform Certificate. The platform certificate serial number is required for this interface to request the http header “Wechatpay-Serial”.

Use the public key of the Wechat Pay platform certificate to perform RSA encryption for the parameter values that need to be encrypted. RSA/ECB/PKCS1Padding is used for the encryption method of JAVA; and OPENSSL_PKCS1_PADDING is used for that of PHP.

The encrypted ciphertext is encoded with Base64 and used as the values of corresponding parameters in the request.

Code example-JAVA

1
2    // Onboarding Sub-merchant API
3    public void onboardingSubMerchant() throws IOException {
4		String onboardingSubMerchantBody = """{
5	"sp_appid": "wx82ec4jy334ner1",
6    "sp_mchid": "2422128905",
7    "name": "testname",
8    "shortname": "shortname",
9    "office_phone": "13680534111",
10    "contact": {
11        "email": "gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==",  // sensitive field, encryption content
12        "name": "Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==",  // sensitive field, encryption content
13        "phone": "l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=="   // sensitive field, encryption content
14    }, 
15    "business_category": 343,
16    "merchant_country_code": "344",
17    "merchant_type": "ENTERPRISE",
18    "registration_certificate_number": "519723407213085723",
19    "registration_certificate_date": "2022-06-03",
20    "settlement_bank_number": "559304578245298347923856",
21    "business": {
22        "business_type": "ONLINE",
23        "mcc": "5344",
24        "mini_program": "flowerplus"
25    },
26    "director": {
27        "name": "Tom",
28        "number": "1234567890"
29    }
30}""";
31        HttpPost httpPost = new HttpPost("https://apihk.mch.weixin.qq.com/v3/global/merchants");
32        httpPost.addHeader("Accept", "application/json");
33        httpPost.addHeader("Content-type", "application/json; charset=utf-8");
34        httpPost.addHeader("Wechatpay-Serial", "0798ABFDCBXXXXXXXXXXXXXXXXXXXXXXX054A761");
35        httpPost.setEntity(new StringEntity(verifyIdInfoBody));
36        CloseableHttpResponse response = httpClient.execute(httpPost);
37        //Process the response
38    }
39

Code example-Go

1
2// Onboarding Sub-merchant API
3func onboardingSubMerchant() {
4   onboardingSubMerchantBody := `{
5	"sp_appid": "wx82ec4jy334ner1",
6    "sp_mchid": "2422128905",
7    "name": "testname",
8    "shortname": "shortname",
9    "office_phone": "13680534111",
10    "contact": {
11        "email": "gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==",
12        "name": "Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==",
13        "phone": "l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=="
14    }, 
15    "business_category": 343,
16    "merchant_country_code": "344",
17    "merchant_type": "ENTERPRISE",
18    "registration_certificate_number": "519723407213085723",
19    "registration_certificate_date": "2022-06-03",
20    "settlement_bank_number": "559304578245298347923856",
21    "business": {
22        "business_type": "ONLINE",
23        "mcc": "5344",
24        "mini_program": "flowerplus"
25    },
26    "director": {
27        "name": "Tom",
28        "number": "1234567890"
29    }
30}`
31   header.Add("Wechatpay-Serial", "")
32   header.Add("Idempotency-Key", "20220518-001")
33   result, err := client.Post(ctx, "https://apihk.mch.weixin.qq.com/v3/global/merchants", header, nil, idVerificationBody, "application/json")
34   if err != nil {
35      // Process error
36   }
37   log.Printf("%s", result.Response.Body)
38}

Code example-PHP

1
2// Onboarding Sub-merchant API
3public function onboardingSubMerchant($instance, $platformPublicKeyInstance, $platformCertificateSerial){
4    $encryptor = static function(string $msg) use ($platformPublicKeyInstance): string {
5        return Rsa::encrypt($msg, $platformPublicKeyInstance, OPENSSL_PKCS1_PADDING);
6    };
7    try {
8        $resp = $instance
9            ->chain('/v3/global/merchants')
10            ->post([
11                'json' => [
12                    'sp_appid' => 'wx82ec4jy334ner1',
13                    'sp_mchid' => '2422128905',
14                    'name' => 'testname',
15                    'shortname' => 'shortname',
16                    'office_phone' => '13680534111',
17                    'contact' => [
18                        'email' => 'gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==',
19                        'name' => 'Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==',
20                        'phone' => 'l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=='
21                    ],
22                    'business_category' => 343,
23                    'merchant_country_code' => '344',
24                    'merchant_type' => 'ENTERPRISE',
25                    'registration_certificate_number' => '519723407213085723',
26                    'registration_certificate_date' => '2022-06-03',
27                    'settlement_bank_number' => '559304578245298347923856',
28                    'business' => [
29                        'business_type' => 'ONLINE',
30                        'mcc' => '5344',
31                        'mini_program' => 'flowerplus'
32                    ],
33                    'director' => [
34                        'name' => 'Tom',
35                        'number' => '1234567890'
36                    ]
37                ],
38                'headers' => [
39                    'Wechatpay-Serial' => $platformCertificateSerial
40                ]
41            ]);
42        echo $resp->getStatusCode(), PHP_EOL;
43        echo $resp->getBody(), PHP_EOL;
44    } catch (\Exception $e) {
45        // Exception handling
46    }
47}

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

3.2.2 Query sub-merchant

Procedure: This is for the merchant to query whether the sub-merchant is created successfully. The interface allows to query the information of a single sub-merchant only.

Code example-JAVA

1
2    // Query Sub-merchant API
3    public void querySubMerchant() throws IOException {
4        HttpGet httpGet = new HttpGet("https://apihk.mch.weixin.qq.com/v3/global/merchants/{$sub_mchid}?sp_appid=wx8888888888888888&sp_mchid=1900000100");
5        httpGet.addHeader("Accept", "application/json");
6        httpGet.addHeader("Content-type", "application/json; charset=utf-8");
7        CloseableHttpResponse response = httpClient.execute(httpGet);
8        //Process the response 
9    }
10

Code example-Go

1
2// Query Sub-merchant API
3func querySubMerchant() {
4   result, err := client.Get(ctx, "https://apihk.mch.weixin.qq.com/v3/global/merchants/{$sub_mchid}?sp_appid=wx8888888888888888&sp_mchid=1900000100")
5   if err != nil {
6      // Process error
7   }
8   log.Printf("%s", result.Response.Body)
9}

Code example-PHP

1
2// Query Sub-merchant API
3public function querySubMerchant($instance){
4    try {
5        $resp = $instance
6            ->chain('/v3/global/merchants/{$sub_mchid}')
7            ->get([
8                'query' => [
9                    'sp_appid' => 'wx8888888888888888',
10                    'sp_mchid' => '1900000100',
11                ]
12            ]);
13        echo $resp->getStatusCode(), PHP_EOL;
14        echo $resp->getBody(), PHP_EOL;
15    } catch (\Exception $e) {
16        // Exception handling
17    }
18}

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

3.2.3 Modify sub-merchant

Procedure: After creating the sub-merchant, the interface allows to modify the sub-merchant information

Encryption method:

Obtain the Weixin Pay Platform certificate and the corresponding platform certificate serial number, Obtain WeChat Pay Platform Certificate. The platform certificate serial number is required for this interface to request the http header “Wechatpay-Serial”.

Use the public key of the Wechat Pay platform certificate to perform RSA encryption for the parameter values that need to be encrypted. RSA/ECB/PKCS1Padding is used for the encryption method of JAVA; and OPENSSL_PKCS1_PADDING is used for that of PHP.

The encrypted ciphertext is encoded with Base64 and used as the values of corresponding parameters in the request.

Code example-JAVA

1
2// Sub Merchant Modifying API
3    public void modifySubMerchant() throws IOException {
4		String modifySubMerchantBody = """{
5	"sub_mchid": "20000100",
6	"sp_appid": "wx82ec4jy334ner1",
7    "sp_mchid": "2422128905",
8    "name": "testname",
9    "shortname": "shortname",
10    "office_phone": "13680534111",
11    "contact": {
12        "email": "gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==",  // sensitive field, encryption content
13        "name": "Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==",  // sensitive field, encryption content
14        "phone": "l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=="   // sensitive field, encryption content
15    }, 
16    "business_category": 343,
17    "merchant_country_code": "344",
18    "merchant_type": "ENTERPRISE",
19    "registration_certificate_number": "519723407213085723",
20    "registration_certificate_date": "2022-06-03",
21    "settlement_bank_number": "559304578245298347923856",
22    "business": {
23        "business_type": "ONLINE",
24        "mcc": "5344",
25        "mini_program": "flowerplus"
26    },
27    "director": {
28        "name": "Tom",
29        "number": "1234567890"
30    }
31}""";
32        httpPut httpPut = new httpPut("https://apihk.mch.weixin.qq.com/v3/global/merchants");
33        httpPut.addHeader("Accept", "application/json");
34        httpPut.addHeader("Content-type", "application/json; charset=utf-8");
35        httpPut.addHeader("Wechatpay-Serial", "0798ABFDCBXXXXXXXXXXXXXXXXXXXXXXX054A761");
36        httpPut.setEntity(new StringEntity(verifyIdInfoBody));
37        CloseableHttpResponse response = httpClient.execute(httpPut);
38        //Process the response
39    }
40

Code example-Go

1
2// Sub Merchant Modifying API
3func modifySubMerchant() {
4   modifySubMerchantBody := `{
5	"sub_mchid": "20000100",
6	"sp_appid": "wx82ec4jy334ner1",
7    "sp_mchid": "2422128905",
8    "name": "testname",
9    "shortname": "shortname",
10    "office_phone": "13680534111",
11    "contact": {
12        "email": "gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==",
13        "name": "Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==",
14        "phone": "l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=="
15    }, 
16    "business_category": 343,
17    "merchant_country_code": "344",
18    "merchant_type": "ENTERPRISE",
19    "registration_certificate_number": "519723407213085723",
20    "registration_certificate_date": "2022-06-03",
21    "settlement_bank_number": "559304578245298347923856",
22    "business": {
23        "business_type": "ONLINE",
24        "mcc": "5344",
25        "mini_program": "flowerplus"
26    },
27    "director": {
28        "name": "Tom",
29        "number": "1234567890"
30    }
31}`
32   header.Add("Wechatpay-Serial", "")
33   header.Add("Idempotency-Key", "20220518-001")
34   result, err := client.Put(ctx, "https://apihk.mch.weixin.qq.com/v3/global/merchants", header, nil, idVerificationBody, "application/json")
35   if err != nil {
36      // Process error
37   }
38   log.Printf("%s", result.Response.Body)
39}

Code example-PHP

1
2// Sub Merchant Modifying API
3public function modifySubMerchant($instance, $platformPublicKeyInstance, $platformCertificateSerial){
4    $encryptor = static function(string $msg) use ($platformPublicKeyInstance): string {
5        return Rsa::encrypt($msg, $platformPublicKeyInstance, OPENSSL_PKCS1_PADDING);
6    };
7    try {
8        $resp = $instance
9            ->chain('/v3/global/merchants')
10            ->put([
11                'json' => [
12					'sub_mchid': '20000100',
13                    'sp_appid' => 'wx82ec4jy334ner1',
14                    'sp_mchid' => '2422128905',
15                    'name' => 'testname',
16                    'shortname' => 'shortname',
17                    'office_phone' => '13680534111',
18                    'contact' => [
19                        'email' => 'gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==',
20                        'name' => 'Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==',
21                        'phone' => 'l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=='
22                    ],
23                    'business_category' => 343,
24                    'merchant_country_code' => '344',
25                    'merchant_type' => 'ENTERPRISE',
26                    'registration_certificate_number' => '519723407213085723',
27                    'registration_certificate_date' => '2022-06-03',
28                    'settlement_bank_number' => '559304578245298347923856',
29                    'business' => [
30                        'business_type' => 'ONLINE',
31                        'mcc' => '5344',
32                        'mini_program' => 'flowerplus'
33                    ],
34                    'director' => [
35                        'name' => 'Tom',
36                        'number' => '1234567890'
37                    ]
38                ],
39                'headers' => [
40                    'Wechatpay-Serial' => $platformCertificateSerial
41                ]
42            ]);
43        echo $resp->getStatusCode(), PHP_EOL;
44        echo $resp->getBody(), PHP_EOL;
45    } catch (\Exception $e) {
46        // Exception handling
47    }
48}

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

4. Applying for H5 payment authorization for sub-merchants using onboarding sub-merchant interface

To allow institutions to apply for H5 payment authorization for sub-merchants while submitting a sub-merchant application, we have integrated H5 authorization request function within the sub-merchant onboard/modify/query API interfaces.

4.1. H5 payment authorization state definition and transition

In the return package of the sub-merchant onboard/modify/query API interface, h5_authorization_state shows the state of the sub-merchant's H5 payment authorization. The state will determine what you should do for the sub-merchant:

● UNAUTHORIZED: H5 Payment authorization has not be granted to the sub-merchant by the WeChat Pay system. Please request for H5 payment authorization for the sub-merchant by filling in the application information in the WeChat Pay Open Platform - Modify Sub-merchant. Alternatively, you can also go directly to the WeChat Pay Open Platform - Onboard Sub-merchant and fill in the H5 application information to directly obtain a list of sub-merchants whose H5 payment authorization state is UNDER_REVIEW.

● UNDER_REVIEW: Your H5 payment authorization application is being processed. A WeChat Pay reviewer will review the request in around 3-5 working days. Please check the review results at the WeChat Pay Open Platform - Query Sub-merchant.

● REJECETED: Your H5 payment authorization application has been rejected. Please go to the WeChat Pay Open Platform - Query Sub-merchant to check the reason for the rejection and use the WeChat Pay Open Platform - Modify Sub-merchant to update the H5 application information.

● APPROVED: Your H5 payment authorization application has been approved and H5 payment authorization has been granted. If you need to edit the H5 payment domain name, please do so at the WeChat Pay Open Platform - Modify Sub-merchant (note: domain names will be fully updated based on your input).

● UNDER_PUNISHMENT: The sub-merchant is being penalized for the violation of WeChat Pay regulations, please contact your BD for assistance.

● APPLICATION_FAILED: Your H5 payment authorization request is not successful. Please go to the WeChat Pay Open Platform - Query Sub-merchant to check the reason and use the WeChat Pay Open Platform - Modify Sub-merchant to update the H5 application information and apply for it again.

Development Guidelines

1. API Rules

2. Development Environment Setup

JAVA

2.1.1. Conditions of Use

2.1.2. Installation

2.1.3. Initialization

2.1.4. General Functions

Golang

2.2.1. Conditions of Use

2.2.2. Installation

2.2.3. Initialization

2.2.4. General Functions

PHP

2.3.1. Conditions of Use

2.3.2. Installation

2.3.3. Initialization

2.3.4. General Functions

3. Fast Access

3.1. Business Sequence Chart

Query sub-merchant's status

What to do when sub-merchant has not completed the onboarding review

3.2. Example of API access

3.2.1 Inbound sub-merchant

3.2.2 Query sub-merchant

3.2.3 Modify sub-merchant

4. Applying for H5 payment authorization for sub-merchants using onboarding sub-merchant interface

4.1. H5 payment authorization state definition and transition

4.2. Sub-merchant apply H5 payment authorization process flowchart