WeChat Pay

WeChat Pay is the main payment method in mainland China.

Setup

1. Register a WeChat Pay merchant account

   • Go to the WeChat Pay Merchant Platform
   • Prepare a business license, the legal representative's ID, and related documents
   • Finish business verification (usually 1–7 business days)

2. Collect the merchant parameters

   • App ID: the WeChat Official Account or Mini Program app ID
   • Merchant ID (Mch ID): the merchant number assigned by WeChat Pay
   • API key: generated under account settings in the merchant platform

3. Download the merchant certificate

   • In the merchant platform, open Account Center (账户中心) → API Security (API安全) and download the certificate
   • You need apiclient_key.pem (private key) and apiclient_cert.pem (certificate)
   • Convert the file contents into environment variables (see below)

4. Get the WeChat Pay public key (recommended, optional)

   WeChat Pay offers two signature checks:

   WeChat Pay public key (recommended)

   • The newer method, introduced in 2024
   • Faster, with no extra network request
   • No expiry
   • You set the environment variables yourself

   Platform certificate (automatic fallback)

   • The older method
   • Used automatically when the public key is unset
   • The app makes one extra request to fetch the certificate
   • Certificates expire after 5 years

5. Set the notify URL

   • Set WECHAT_PAY_NOTIFY_URL as shown in the next section

Environment variables

Add these to .env:

# WeChat Pay
WECHAT_PAY_APP_ID=wx1234567890abcdef    # WeChat app ID
WECHAT_PAY_MCH_ID=1234567890            # Merchant ID
WECHAT_PAY_API_KEY=your-32-char-api-key # API key
# Must be a public HTTPS URL. For local development, use a tunnel.
# Keep the path /api/payment/webhook/wechat. See the payment testing guide.
WECHAT_PAY_NOTIFY_URL=https://yourdomain.com/api/payment/webhook/wechat

# Merchant certificate (required). Used to sign API requests.
WECHAT_PAY_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEA...\n-----END RSA PRIVATE KEY-----"
WECHAT_PAY_PUBLIC_KEY="-----BEGIN CERTIFICATE-----\nMIIEpDCCA4ygAwIBAgIU...\n-----END CERTIFICATE-----"

# WeChat Pay public key verification (recommended, optional).
# When these are set, verification skips an extra network request.
# When they are unset, the app falls back to the platform certificate.
WECHAT_PAY_PAYMENT_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEA...\n-----END PUBLIC KEY-----"
WECHAT_PAY_PUBLIC_KEY_ID="PUB_KEY_ID_0000000000000024101100397200000006"

The webhook path is https://yourdomain.com/api/payment/webhook/wechat.

Convert certificates to one line

If you already have the certificate files, flatten them:

# Merchant private key
awk '{printf "%s\\n", $0}' apiclient_key.pem

# Merchant certificate
awk '{printf "%s\\n", $0}' apiclient_cert.pem

# WeChat Pay public key (the .pem file from the merchant platform)
awk '{printf "%s\\n", $0}' pub_key.pem

Paste each result into the matching environment variable.

Signature verification

The app picks the best available method:

Suggestions:

• Best performance: set the WeChat Pay public key so the app skips the extra request
• Smallest setup: merchant certificate only. The app still works, with a bit more latency
• Recommended: set both

Download the WeChat Pay public key (optional)

Do this only when you want the faster verification path:

1. Sign in to the WeChat Pay Merchant Platform

   • Open pay.weixin.qq.com
   • Sign in as a super admin (超级管理员) or security contact (安全联系人)

2. Open API Security

   • In the left menu, open Account Center (账户中心)
   • Open API Security (API安全)

3. Request and download the public key

   • Find WeChat Pay public key (微信支付公钥)
   • Click Apply for public key (申请公钥)
   • Download the .pem file

4. Copy the public key ID

   • The download page or key details show the ID
   • It looks like PUB_KEY_ID_0000000000000024101100397200000006
   • Put that ID in WECHAT_PAY_PUBLIC_KEY_ID

5. Set the environment variables

   • Flatten the public key with the awk command above
   • Set WECHAT_PAY_PAYMENT_PUBLIC_KEY and WECHAT_PAY_PUBLIC_KEY_ID

Reference: WeChat Pay public key verification

To start quickly, skip this section and configure only the merchant certificate.

Notes

• WeChat Pay accepts CNY only
• One-time payments only. Subscriptions are not supported
• A Chinese business license is required. Individuals cannot apply
• The notify URL must be HTTPS
• Certificate values are secrets. Keep them in environment variables
• The WeChat Pay public key is optional and avoids an extra network request
• When the public key is unset, the app falls back to the platform certificate
• There is no sandbox. Test with a real ¥0.01 charge. See the payment testing guide

Plan example

amount is in yuan. The provider multiplies by 100 before it calls WeChat Pay. 0.01 is a ¥0.01 test charge.

monthlyWechat: {
  provider: 'wechat',
  id: 'monthlyWechat',          // Each plan needs its own id
  amount: 0.01,                 // Yuan. The provider multiplies by 100
  currency: 'CNY',
  duration: {
    months: 1,
    type: 'one_time'            // WeChat Pay is one-time only
  },
  i18n: {
    'en': {
      name: 'Monthly Plan',
      description: 'One-time monthly access via WeChat Pay',
      duration: 'month',
      features: ['All premium features', 'Priority support']
    },
  }
}

Create the provider with createPaymentProvider('wechat').

Back to Payment overview