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. Application Form Status Transfer Map

Definitions:

• PENDING：The application form is queued for processing, and is expected to be reviewed (UNDER_REVIEW) in about one minute. If not, the merchant can check whether the merchant onboarding status (institution) or the signing status with the parent merchant (service provider) is completed.

• UNDER_REVIEW ：The application form is complete, and the WeChat Pay reviewer will review the form in about 3 working days

• REJECTED：The application form is rejected. The merchant can check the reason for rejection in the audit_reject_detail field in the application form details. The merchant can modify and resubmit the application form (Modify) Note: Only application forms rejected by a reviewer can be modified.>

• APPROVED：The application is approved, and H5 payment is enabled.

4. H5 Payment Permission Status Transfer Map

Definitions: (Note: There should be only one application form for one permission type)

• UNAUTHORIZED：The sub-merchant has not enabled payment with the WeChat Pay System.

• AUTHORITY_TO_TEST：The sub-merchant test website is not yet launched, and the limit for sub-merchant is ① 1000 CNY/day/person; ② 50000 CNY/day/sub-merchant.

• FORMAL_AUTHORITY：The sub-merchant website has been launched, and the limit for sub-merchant is ① 50000 CNY/day/person; ② 500000 CNY/day/sub-merchant.

• AUTHORIZED：The sub-merchant has been granted full payment permission without limit. Unlimited payment is not available for merchants without the FORMAL_AUTHORITY payment permission.

• UNDER_PUNISHMENT：The sub-merchant is in the punishment stage for violating WeChat payment regulations.

5. Business Sequence Map

5.1 Institution/service provider applies for H5 payment on behalf of its sub-merchant

Key steps:

• Step 1.2: Before submitting a permission to the WeChat Pay System, the institution/service provider must check the integrity of merchant data, including the license validity, registration number, contact information/email of the sub-merchant.

• Step 1.3: Before submitting a permission application to the WeChat Pay System, the institution/service should check the legality and integrity of the application materials submitted. To apply for ultra-low-limit payment without launching a website, change the website_state field to [UN_LAUNCHED] and upload screenshots of the website business page (website_business_page_pics) and website homepage ( website_homepage_pics) for review. To apply for unlimited H5 payment, upload the company profile, business description, (business_description) and company registration certificate (company_register_cert), and explicitly declare the transaction limit type (transaction_limit_type) as [NO_LIMIT]. The application will be approved by the System, an application form for canceling limit will be automatically generated (Step 2.2), and the merchant will be automatically informed of the review results of the application (Step 5.2).

• Step 1.4: To avoid any unnecessary communication between the merchant system and the WeChat Pay System, when the merchant system is applying for permissions for sub-merchants, the merchant system should check whether the merchant has been granted the related H5 payment permission (WeChat Pay Overseas Document - Application for H5 Payment Permission) or whether any application form of the sub-merchant is pending review (Step 1.7).

• Step 5.2: If [NO_LIMIT] is selected and the application is successfully submitted and approved, the WeChat Pay System will automatically establish an application form for limit cancellation (without directly informing the merchant system of this process), and inform the merchant by callback after review. Thus, the merchant system should decrypt the callback (WeChat Pay Overseas Document - Application for H5 Payment Permission) and check if [APPLY_FOR_RELIEVE_LIMITED] is written in the sub-merchant ID (sub_mchid) application type (applyment_type) field to determine the review results of the sub-merchant limit cancellation application.

5.2 Modifying H5 permission application

Key steps:

• Step 1.4 and Step 3.2: To modify a rejected application form (there should be only one application form for one H5 payment permission type. It is impossible to create an application form of the same type through WeChat Pay Overseas Document - Application for H5 Payment Permission). The merchant system should duly save the application form ID and information from the WeChat Pay System after successfully establishing an application for H5 payment permission (Step 1.4), and modify and report the application status and application form ID according to the review results from the WeChat Pay System (Step 3.2), so as to resubmit the application in case of rejection.

• Step 4.1: Before modifying an application form, the merchant should change the application form format to PATCH so as to update the submitted fields only, with other fields unchanged. The modified application form must meet all requirements for creating an application for H5 payment permission.

5.3 Institution/service provider upgrades sub-merchant payment permission to NO_LIMIT

关键步骤解读：

• Step 1.2 and Step 1.3: Same as the case of creating an application for H5 payment permission, the merchant data in the application to cancel limit submitted by the merchant system to the WeChat Pay System must be integral and legal. It is necessary to upload the business description (business_description) and company registration certificate (company_register_cert), and explicitly declare the limit type (transaction_limit_type) as [NO_LIMIT].

• Step 1.4: As the sub-merchant selected [NO_LIMIT] for the transaction_limit_type in the previous H5 payment permission application which has been approved, the merchant system should check whether there is already an application for canceling limit for such merchant before submitting an application for the same purpose.

• Step 1.5: The H5 payment permission of a common limit [FORMAL_AUTHORITY] is the prerequisite for applying for canceling limit.

5.4 To modify/add/delete sub-merchant’s H5 payment domain name

Key steps:

• Step 1.2 and Step 1.3: Same as the case of creating an application for H5 payment permission, the merchant data in the application for modifying domain name submitted by the merchant system to the WeChat Pay System must be integral and legal.

• Step 1.4: Before applying for H5 payment domain name modification, the sub-merchant must enable the H5 payment (any transaction_limit_type).

• Step 1.5: The current payment domain of the sub-merchant will be overwritten by the domain name submitted by the merchant system. Maximum 5 domain names can be submitted per time.

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. Application Form Status Transfer Map

4. H5 Payment Permission Status Transfer Map

5. Business Sequence Map

5.1 Institution/service provider applies for H5 payment on behalf of its sub-merchant

5.2 Modifying H5 permission application

5.3 Institution/service provider upgrades sub-merchant payment permission to NO_LIMIT

5.4 To modify/add/delete sub-merchant’s H5 payment domain name