Development Guidelines

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 Golang PHP

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

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

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

<dependency>
<groupId>com.github.wechatpay-apiv3</groupId>
<artifactId>wechatpay-apache-httpclient</artifactId>
<version>0.4.7</version>
</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.


    private CloseableHttpClient httpClient;
    private CertificatesManager certificatesManager;
    private Verifier verifier;

    @Before
    //initialize verifier and build httpClient
    public void setup() throws GeneralSecurityException, IOException, HttpCodeException, NotFoundException {

        PrivateKey merchantPrivateKey = PemUtil.loadPrivateKey(privateKey);
        certificatesManager = CertificatesManager.getInstance();
        certificatesManager.putMerchant(merchantId, new WechatPay2Credentials(merchantId,
                        new PrivateKeySigner(merchantSerialNumber, merchantPrivateKey)),
                apiV3Key.getBytes(StandardCharsets.UTF_8));
        verifier = certificatesManager.getVerifier(merchantId);
        WechatPayHttpClientBuilder builder = WechatPayHttpClientBuilder.create()
                .withMerchant(merchantId, merchantSerialNumber, merchantPrivateKey)
                .withValidator(new WechatPay2Validator(verifier));
        httpClient = builder.build();
    }

2.1.4. General Functions

Encrypting Sensitive Information Decrypting Sensitive Information


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


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

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.


import (
   "context"
   "crypto/rand"
   "crypto/rsa"
   "crypto/x509"
   "encoding/base64"
   "fmt"
   "github.com/wechatpay-apiv3/wechatpay-go/core"
   "github.com/wechatpay-apiv3/wechatpay-go/core/option"
   "github.com/wechatpay-apiv3/wechatpay-go/utils"
   "log"
   "net/http"
)

var (
   mchID                      = ""                  // merchant id
   mchCertificateSerialNumber = "" // merchant certificate serial number
   mchAPIv3Key                = ""                  // merchant api v3 key
   header                     = make(http.Header)
   ctx                        = context.Background()
   cert                       *x509.Certificate
   mchPrivateKey              *rsa.PrivateKey
   client                     *core.Client
   err                        error
)

func setup() {
   //Load platform certificate
   cert, err = utils.LoadCertificateWithPath("Path/To/Platform/Cert")
   if err != nil {
      log.Fatal(err)
   }
   // Load private key
   mchPrivateKey, err = utils.LoadPrivateKeyWithPath("Path/To/Private/Key")
   if err != nil {
      log.Fatal("load merchant private key error")
   }
   // Initialize client which is capable to update platform certificate periodically
   opts := []core.ClientOption{
      option.WithWechatPayAutoAuthCipher(mchID, mchCertificateSerialNumber, mchPrivateKey, mchAPIv3Key),
   }
   client, err = core.NewClient(ctx, opts...)
   if err != nil {
      log.Fatalf("new wechat pay client err:%s", err)
   }
}

2.2.4. General Functions

Encrypting Sensitive Information Decrypting Sensitive Information


func Encryption(t *testing.T) {
	var testRSACryptoUtilMchCertificateStr = `-----BEGIN CERTIFICATE-----
	-----END CERTIFICATE-----`
	testRSACryptoUtilCertificate, _ = LoadCertificate(testRSACryptoUtilMchCertificateStr)
   const message = "hello world"
   
   // Encrypt the certificate by OAEP padding
   ciphertext, _ := EncryptOAEPWithCertificate(message, testRSACryptoUtilCertificate)
   
  // Encrypt the certificate by PKCS1 padding
   ciphertext, _ := EncryptPKCS1v15WithCertificate(message, testRSACryptoUtilCertificate)
}


func TestDecryption(t *testing.T) {
	var testRSACryptoUtilPrivateKeyStr = `-----BEGIN PRIVATE KEY-----
-----END PRIVATE KEY-----`
	testRSACryptoUtilPrivateKey, _ = LoadPrivateKey(testingKey(testRSACryptoUtilPrivateKeyStr))
	const ciphertext = ""

	// Decrypt the private key by PKCS1 padding
	decryptMessage, _ := DecryptPKCS1v15(ciphertext, testRSACryptoUtilPrivateKey)

	// Decrypt the private key by OAEP padding
	decryptMessage, _ := DecryptOAEP(ciphertext, testRSACryptoUtilPrivateKey)
}

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.


require_once('vendor/autoload.php');

use WeChatPay\Builder;
use WeChatPay\Crypto\Rsa;
use WeChatPay\Util\PemUtil;

$merchantId = '190000****';
$merchantPrivateKeyFilePath = 'file:///path/to/merchant/apiclient_key.pem';
$merchantPrivateKeyInstance = Rsa::from($merchantPrivateKeyFilePath, Rsa::KEY_TYPE_PRIVATE);
$merchantCertificateSerial = '3775B6A45ACD588826D15E583A95F5DD********';
$platformCertificateFilePath = 'file:///path/to/wechatpay/cert.pem';
$platformPublicKeyInstance = Rsa::from($platformCertificateFilePath, Rsa::KEY_TYPE_PUBLIC);
$platformCertificateSerial = PemUtil::parseCertificateSerialNo($platformCertificateFilePath);

// init a API V3 instance
$instance = Builder::factory([
    'mchid'      => $merchantId,
    'serial'     => $merchantCertificateSerial,
    'privateKey' => $merchantPrivateKeyInstance,
    'certs'      => [
        $platformCertificateSerial => $platformPublicKeyInstance,
    ],
]);

2.3.4. General Functions

Encrypting Sensitive Information Decrypting Sensitive Information


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


    $decryptor = static function(string $msg) use ($merchantPrivateKeyInstance): string {
        return Rsa::decrypt($msg, $merchantPrivateKeyInstance, OPENSSL_PKCS1_PADDING);
    };
	$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 Response for failed onboarding Response when onboarding requires further manual review


{
	"sub_mchid": "20000100",
	"verification_status": "Approved"
}


{
  "code": "INVALID_REQUEST",
  "message": "Parameter format verification error",
  "detail": {
    "field": "#/properties/payer",
    "value": "1346177081915535577",
    "issue": "Does not match the ALLOF schema",
    "location": "body"
  }
}


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

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 Go PHP


    // Onboarding Sub-merchant API
    public void onboardingSubMerchant() throws IOException {
		String onboardingSubMerchantBody = """{
	"sp_appid": "wx82ec4jy334ner1",
    "sp_mchid": "2422128905",
    "name": "testname",
    "shortname": "shortname",
    "office_phone": "13680534111",
    "contact": {
        "email": "gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==",  // sensitive field, encryption content
        "name": "Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==",  // sensitive field, encryption content
        "phone": "l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=="   // sensitive field, encryption content
    }, 
    "business_category": 343,
    "merchant_country_code": "344",
    "merchant_type": "ENTERPRISE",
    "registration_certificate_number": "519723407213085723",
    "registration_certificate_date": "2022-06-03",
    "settlement_bank_number": "559304578245298347923856",
    "business": {
        "business_type": "ONLINE",
        "mcc": "5344",
        "mini_program": "flowerplus"
    },
    "director": {
        "name": "Tom",
        "number": "1234567890"
    }
}""";
        HttpPost httpPost = new HttpPost("https://apihk.mch.weixin.qq.com/v3/global/merchants");
        httpPost.addHeader("Accept", "application/json");
        httpPost.addHeader("Content-type", "application/json; charset=utf-8");
        httpPost.addHeader("Wechatpay-Serial", "0798ABFDCBXXXXXXXXXXXXXXXXXXXXXXX054A761");
        httpPost.setEntity(new StringEntity(verifyIdInfoBody));
        CloseableHttpResponse response = httpClient.execute(httpPost);
        //Process the response
    }


// Onboarding Sub-merchant API
func onboardingSubMerchant() {
   onboardingSubMerchantBody := `{
	"sp_appid": "wx82ec4jy334ner1",
    "sp_mchid": "2422128905",
    "name": "testname",
    "shortname": "shortname",
    "office_phone": "13680534111",
    "contact": {
        "email": "gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==",
        "name": "Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==",
        "phone": "l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=="
    }, 
    "business_category": 343,
    "merchant_country_code": "344",
    "merchant_type": "ENTERPRISE",
    "registration_certificate_number": "519723407213085723",
    "registration_certificate_date": "2022-06-03",
    "settlement_bank_number": "559304578245298347923856",
    "business": {
        "business_type": "ONLINE",
        "mcc": "5344",
        "mini_program": "flowerplus"
    },
    "director": {
        "name": "Tom",
        "number": "1234567890"
    }
}`
   header.Add("Wechatpay-Serial", "")
   header.Add("Idempotency-Key", "20220518-001")
   result, err := client.Post(ctx, "https://apihk.mch.weixin.qq.com/v3/global/merchants", header, nil, idVerificationBody, "application/json")
   if err != nil {
      // Process error
   }
   log.Printf("%s", result.Response.Body)
}


// Onboarding Sub-merchant API
public function onboardingSubMerchant($instance, $platformPublicKeyInstance, $platformCertificateSerial){
    $encryptor = static function(string $msg) use ($platformPublicKeyInstance): string {
        return Rsa::encrypt($msg, $platformPublicKeyInstance, OPENSSL_PKCS1_PADDING);
    };
    try {
        $resp = $instance
            ->chain('/v3/global/merchants')
            ->post([
                'json' => [
                    'sp_appid' => 'wx82ec4jy334ner1',
                    'sp_mchid' => '2422128905',
                    'name' => 'testname',
                    'shortname' => 'shortname',
                    'office_phone' => '13680534111',
                    'contact' => [
                        'email' => 'gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==',
                        'name' => 'Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==',
                        'phone' => 'l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=='
                    ],
                    'business_category' => 343,
                    'merchant_country_code' => '344',
                    'merchant_type' => 'ENTERPRISE',
                    'registration_certificate_number' => '519723407213085723',
                    'registration_certificate_date' => '2022-06-03',
                    'settlement_bank_number' => '559304578245298347923856',
                    'business' => [
                        'business_type' => 'ONLINE',
                        'mcc' => '5344',
                        'mini_program' => 'flowerplus'
                    ],
                    'director' => [
                        'name' => 'Tom',
                        'number' => '1234567890'
                    ]
                ],
                'headers' => [
                    'Wechatpay-Serial' => $platformCertificateSerial
                ]
            ]);
        echo $resp->getStatusCode(), PHP_EOL;
        echo $resp->getBody(), PHP_EOL;
    } catch (\Exception $e) {
        // Exception handling
    }
}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

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 Go PHP


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


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


// Query Sub-merchant API
public function querySubMerchant($instance){
    try {
        $resp = $instance
            ->chain('/v3/global/merchants/{$sub_mchid}')
            ->get([
                'query' => [
                    'sp_appid' => 'wx8888888888888888',
                    'sp_mchid' => '1900000100',
                ]
            ]);
        echo $resp->getStatusCode(), PHP_EOL;
        echo $resp->getBody(), PHP_EOL;
    } catch (\Exception $e) {
        // Exception handling
    }
}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

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

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 Go PHP


// Sub Merchant Modifying API
    public void modifySubMerchant() throws IOException {
		String modifySubMerchantBody = """{
	"sub_mchid": "20000100",
	"sp_appid": "wx82ec4jy334ner1",
    "sp_mchid": "2422128905",
    "name": "testname",
    "shortname": "shortname",
    "office_phone": "13680534111",
    "contact": {
        "email": "gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==",  // sensitive field, encryption content
        "name": "Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==",  // sensitive field, encryption content
        "phone": "l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=="   // sensitive field, encryption content
    }, 
    "business_category": 343,
    "merchant_country_code": "344",
    "merchant_type": "ENTERPRISE",
    "registration_certificate_number": "519723407213085723",
    "registration_certificate_date": "2022-06-03",
    "settlement_bank_number": "559304578245298347923856",
    "business": {
        "business_type": "ONLINE",
        "mcc": "5344",
        "mini_program": "flowerplus"
    },
    "director": {
        "name": "Tom",
        "number": "1234567890"
    }
}""";
        httpPut httpPut = new httpPut("https://apihk.mch.weixin.qq.com/v3/global/merchants");
        httpPut.addHeader("Accept", "application/json");
        httpPut.addHeader("Content-type", "application/json; charset=utf-8");
        httpPut.addHeader("Wechatpay-Serial", "0798ABFDCBXXXXXXXXXXXXXXXXXXXXXXX054A761");
        httpPut.setEntity(new StringEntity(verifyIdInfoBody));
        CloseableHttpResponse response = httpClient.execute(httpPut);
        //Process the response
    }


// Sub Merchant Modifying API
func modifySubMerchant() {
   modifySubMerchantBody := `{
	"sub_mchid": "20000100",
	"sp_appid": "wx82ec4jy334ner1",
    "sp_mchid": "2422128905",
    "name": "testname",
    "shortname": "shortname",
    "office_phone": "13680534111",
    "contact": {
        "email": "gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==",
        "name": "Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==",
        "phone": "l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=="
    }, 
    "business_category": 343,
    "merchant_country_code": "344",
    "merchant_type": "ENTERPRISE",
    "registration_certificate_number": "519723407213085723",
    "registration_certificate_date": "2022-06-03",
    "settlement_bank_number": "559304578245298347923856",
    "business": {
        "business_type": "ONLINE",
        "mcc": "5344",
        "mini_program": "flowerplus"
    },
    "director": {
        "name": "Tom",
        "number": "1234567890"
    }
}`
   header.Add("Wechatpay-Serial", "")
   header.Add("Idempotency-Key", "20220518-001")
   result, err := client.Put(ctx, "https://apihk.mch.weixin.qq.com/v3/global/merchants", header, nil, idVerificationBody, "application/json")
   if err != nil {
      // Process error
   }
   log.Printf("%s", result.Response.Body)
}


// Sub Merchant Modifying API
public function modifySubMerchant($instance, $platformPublicKeyInstance, $platformCertificateSerial){
    $encryptor = static function(string $msg) use ($platformPublicKeyInstance): string {
        return Rsa::encrypt($msg, $platformPublicKeyInstance, OPENSSL_PKCS1_PADDING);
    };
    try {
        $resp = $instance
            ->chain('/v3/global/merchants')
            ->put([
                'json' => [
					'sub_mchid': '20000100',
                    'sp_appid' => 'wx82ec4jy334ner1',
                    'sp_mchid' => '2422128905',
                    'name' => 'testname',
                    'shortname' => 'shortname',
                    'office_phone' => '13680534111',
                    'contact' => [
                        'email' => 'gP32/1QSaIpKlaFbWgP3hr8W3+YTtiavMRbOJJ6dATymJzxx/b4YPOTKdeRApW6Nt2ZZB9reZ1x45XhIEF/Ztb6mqfFVb6LxpJlHgDL/zpUG51551XQ3Ww+/kVCJcokiIiT1bSwEcCe6tPL2cmdsOEjlTikyrasLc1bG8vaG/i361r0vX9w56O2Mgv3OnJ4fr4xnmxNcVrJnk1f/gBSIiCUWA0163f3LM4KifQelEuz/WtroeKAzRDiI0/pOvXfwrYDK==',
                        'name' => 'Vxjsrod2RT2aGxeI5i+Z2C4arXYGXZuwE8IrRf6uYu6S5dy4Igw7kjvYWYCNfsgcdXyfjdA4KVntbgSa3zic+ERsOd5u+SNKkaFSH3SwYtpcCyaUMvICTw/6AOY/qy+He9la/gxObgi4zkxvLJmZTJVualTVJWWCIvcuDArW8Kfqp8rBl+IxDEgCojoEmqE7ymVReslGBXWiaPS1UsZx1QJyez3/ijzBa4AKch3XuPx6d3qvM+J8iMx/b94LAfpTihU/j==',
                        'phone' => 'l8JH2dAGLNJ8P5DENoMV0eW4JgIquV2ZO4conHnZp48g/eVpgvIfMj4Ge6LRVENW4eZksErJnYCQB+EOFEGR0lMhA1LexPLu0en08iM2ghkftYWAsOD4JPkvvc36SAfWal29eoZh4maO6kOGW7G4uBua6JoMsEjR6uuw5Gw5DC2eikcdkDBGk9vHSP/oxRs3Qu8a83GikhLgdpAPitXbZX/TEPG5SUg8Fx4BCMCKOfxy8uakq2/EeCtyBMjaiheUePoA=='
                    ],
                    'business_category' => 343,
                    'merchant_country_code' => '344',
                    'merchant_type' => 'ENTERPRISE',
                    'registration_certificate_number' => '519723407213085723',
                    'registration_certificate_date' => '2022-06-03',
                    'settlement_bank_number' => '559304578245298347923856',
                    'business' => [
                        'business_type' => 'ONLINE',
                        'mcc' => '5344',
                        'mini_program' => 'flowerplus'
                    ],
                    'director' => [
                        'name' => 'Tom',
                        'number' => '1234567890'
                    ]
                ],
                'headers' => [
                    'Wechatpay-Serial' => $platformCertificateSerial
                ]
            ]);
        echo $resp->getStatusCode(), PHP_EOL;
        echo $resp->getBody(), PHP_EOL;
    } catch (\Exception $e) {
        // Exception handling
    }
}


									{
										"stock_id": "Python",
										"stock_creator_mchid": "123456",
										"limit": 10,
									}

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

For H5 payment product descriptions, please go to H5 Authorization Application / Product Introduction.

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.

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

Payments

Funding Products

Other Products

Development Guidelines

1. API Rules

2. Development Environment Setup

2.1.1. Conditions of Use

2.1.2. Installation

2.1.3. Initialization

2.1.4. General Functions

2.2.1. Conditions of Use

2.2.2. Installation

2.2.3. Initialization

2.2.4. General Functions

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