Why Offer WeChat Pay?
800M+ Users
WeChat has over 1 billion monthly active users, and WeChat Pay has over 800 million users.
Mobile-First
The customer approves the payment inside the WeChat app, a flow that Chinese customers already know.
Dual Currency
Bill in USD or CNY, depending on the customers you sell to.
Overview
How It Works
Customer Experience
- The customer selects WeChat at checkout and clicks Pay.
- A QR code opens in a full-screen overlay on the checkout page.
- The customer opens WeChat on their phone and scans the QR code. If the customer is already paying on their phone, checkout shows steps to take a screenshot of the QR code and scan it from the WeChat photo album.
- The customer confirms the payment in the WeChat app.
- Checkout detects the completed payment and redirects the customer to your success page.
Customers pay in USD or CNY, and you receive settlement in USD.
Configuration
billing_currency: 'CNY'.
API Method Type
Testing
1
Enable test mode
Turn off the Live Mode switch in the dashboard sidebar, and use API keys created in test mode.
2
Create a test checkout
Create a one-time checkout session with
we_chat_pay in allowed_payment_method_types.3
Scan the QR code
Checkout shows a test QR code. Scan it with your phone’s camera; the WeChat app isn’t needed. The QR code opens a test page where you can authorize or fail the payment.
Best Practices
Target Chinese customers
Target Chinese customers
WeChat Pay is used mostly by Chinese consumers. Include it when your customers include Chinese buyers, or when you sell to the Chinese market.
Always include card fallbacks
Always include card fallbacks
Not every customer has WeChat. Include
credit and debit as fallback payment methods.Optimize for mobile
Optimize for mobile
Scanning is easiest when checkout is open on a computer or tablet and the customer scans with their phone. On a phone, checkout guides the customer to screenshot the QR code and scan it from the WeChat photo album, so keep your checkout page responsive.
Consider both currencies
Consider both currencies
WeChat Pay supports USD and CNY. Choose the billing currency that suits your customers: USD if you price in USD, or CNY to show Chinese customers a price in their own currency. Settlement is in USD either way.
Troubleshooting
WeChat Pay not appearing at checkout
WeChat Pay not appearing at checkout
Check:
- Is
we_chat_payincluded inallowed_payment_method_types? - Is the billing currency USD or CNY?
- Does the amount meet the minimum ($0.50 or 4.00 CNY)?
- Is this a one-time payment? WeChat Pay is not offered on subscriptions.
QR code not scanning
QR code not scanning
Cause: The QR code may have expired, or the customer’s WeChat version is outdated. The QR code expires after a limited time.Solution: If the QR code expired, the customer needs to start a new checkout from your site, or you can create a new checkout session for them. If the code is still valid, ask the customer to update WeChat to a current version.
Payment not confirming
Payment not confirming
Cause: WeChat Pay usually confirms within seconds, but network delays can occur.Solution: Use webhooks for the payment confirmation. If the payment doesn’t confirm within a few minutes, the customer may need to try again.
Related Pages
Payment Methods Overview
See all supported payment methods.
Checkout Guide
Complete checkout implementation guide.
Webhooks
Handle payment confirmations asynchronously.
Asia-Pacific
GCash (Philippines), Alipay HK and FPS (Hong Kong), and Touch ‘n Go (Malaysia).
Testing Process
Complete testing guide for all payment methods.