Master WeChat Pay Integration for Public Accounts and Mini‑Programs

1. Prerequisites for WeChat Pay

1.1 Official Account

WeChat official accounts are divided into service accounts and subscription accounts; service accounts provide advanced features. Payment integration requires a certified service account, and mini‑programs also need certification.

One service account can associate up to 10 mini‑programs under the same entity, or 3 under different entities. If the mini‑program shares the same entity and the account is certified, you can register and certify quickly in the Mini‑Program Management section without paying the 300 RMB certification fee again.

1.2 WeChat Merchant Platform

After certification, enable WeChat Pay in the official account backend. Submit the application; after 3‑5 business days you will receive an email with the merchant number and a small verification transfer to your corporate account.

Merchants are either "ordinary" or "service provider". Ordinary merchants can transact but cannot expand merchants; service providers can expand merchants but cannot transact directly. Service providers act as a unified payment entry and must bind a specific ordinary merchant.

Apply for an ordinary merchant.

1.3 Bind Merchant

WeChat Pay requires binding the merchant number to the app (official account or mini‑program). If the merchant and AppID belong to the same entity, follow two steps: associate AppID in the merchant platform product center, and confirm in the WeChat Pay merchant management of the account.

In Merchant Platform → Product Center → AppID Account Management, associate the AppID.

In the official account or mini‑program backend → WeChat Pay → Merchant Number Management, confirm the binding.

If the merchant and AppID belong to different entities, the same steps apply, but you also need to provide the AppID’s certification information.

2. WeChat Pay Configuration

2.1 Payment Product Types

Supported product types include:

1. Payment Code (scan code)

2. JSAPI (H5 page within WeChat)

3. Native (QR code)

4. APP (mobile app SDK)

5. H5 (outside WeChat browser)

6. Mini‑Program

7. Face Scan

Enable the desired product in Merchant Platform → My Products.

2.2 Payment Authorization Directory

Configure the payment authorization directory (your order‑interface URL) in Merchant Platform → Product Center → Development Configuration. Up to five directories can be configured.

2.3 Merchant Secret Key

Set the API secret key (32‑character random string) in Merchant Platform → Account Center → API Security. Install the operation certificate on first setup.

For API v3 you also need an APIv3 secret and a CA‑issued API certificate.

API v3 secret is used for decrypting platform certificates and callback data.

API certificate enables advanced interfaces such as refunds and red packets.

Check whether your SDK supports v3.

2.4 Server Configuration

Enable server configuration in the official account backend → Development → Basic Configuration → Server Configuration.

2.5 IP Whitelist

Set the developer secret and IP whitelist in the official account backend → Development → Basic Configuration → Official Account Development Info.

2.6 JS Interface Security Domain

Set the JS interface security domain in Official Account Settings → Feature Settings.

Mini‑programs do not require these configurations.

3. WeChat Pay Process

We focus on API v2 because v3 is still evolving. The flow includes order creation, client‑side payment invocation, asynchronous notification, and status query.

3.1 Unified Order Interface

The client initiates payment, the merchant creates an order, and calls the unified order API to obtain a prepay_id.

Request Parameter

Required

Type

Description

appid

Yes

String

Official account appid

mch_id

Yes

String

Merchant number

nonce_str

Yes

String

Random string, up to 32 characters

sign

Yes

String

Signature, MD5 by default

out_trade_no

Yes

String

Internal order number

total_fee

Yes

Int

Total amount in cents

notify_url

Yes

String

Payment result notification URL

Signature generation: sort non‑empty parameters, concatenate with merchant key, and MD5 hash.

Generate a key=value string sorted by key.

Append "&key=MERCHANT_KEY".

MD5 encrypt the result.

3.2 Payment Invocation

In H5 pages call WeixinJSBridge.invoke('getBrandWCPayRequest', …) with parameters appId, timeStamp, nonceStr, package, signType, paySign.

function onBridgeReady() {
    WeixinJSBridge.invoke('getBrandWCPayRequest', {
        "appId":"wx2421b1c4370ec43b",
        "timeStamp":"1395712654",
        "nonceStr":"e61463f8efa94090b1f366cccfbbb444",
        "package":"prepay_id=u802345jgfjsdfgsdg888",
        "signType":"MD5",
        "paySign":"70EA570631E4BB79628FBCA90534C63FF7FADD89"
    }, function(res) {
        if (res.err_msg == "get_brand_wcpay_request:ok") {
            // payment succeeded (but verify asynchronously)
        }
    });
}
if (typeof WeixinJSBridge == "undefined") {
    if (document.addEventListener) {
        document.addEventListener('WeixinJSBridgeReady', onBridgeReady, false);
    } else if (document.attachEvent) {
        document.attachEvent('WeixinJSBridgeReady', onBridgeReady);
        document.attachEvent('onWeixinJSBridgeReady', onBridgeReady);
    }
} else {
    onBridgeReady();
}

Note that res.err_msg == "get_brand_wcpay_request:ok" only indicates that WeChat returned success; the merchant must still confirm the payment via notification.

3.3 Asynchronous Notification

WeChat sends a POST notification to the URL configured in notify_url. The merchant must handle the notification idempotently; WeChat will retry with an exponential back‑off schedule (15 s, 30 s, … up to 24 h 4 min) until a successful response is returned.

Parameter

Required

Type

Description

return_code

Yes

String

SUCCESS / FAIL

return_msg

No

String

Return message

3.4 Payment Status Query

Frontend receives payment result, then calls the query API to confirm status.

Backend processes asynchronous notification and returns the result to WeChat.

If no notification, actively query the order using the order query API.

Reconcile daily transaction statements and handle any missing orders.

4. Summary

This article used public‑account payment as an example to outline the required configurations and workflow for integrating WeChat Pay. The same principles apply to APP and other scenarios; be aware of the ongoing migration from API v2 to v3 and adjust SDK versions accordingly.