Introduction

WeChat is a major mobile payment platform in China, integrated into the WeChat application. It supports transfers, merchant payments, public service fees, and online shopping, primarily through QR codes or payment codes. Users can link bank cards or use wallet balances. It offers mini-program functionality, making it easier for businesses to operate. It adopts multi-factor authentication and encryption technology to ensure security. Widely used in China, it is also expanding overseas and supports multi-currency settlement. Due to its social features, convenience, and extensive ecosystem, WeChat Pay has become an indispensable payment tool in the daily lives of Chinese consumers.

Basic information

Properties

properties	WeChat Pay
Payment Category	APM
Payment Type	E-Wallet
Supported Regions	CN,HK
Payment Method	["WeChat Pay"]
Supported Currencies	Singapore merchant entity:["SGD"] Hong Kong merchant entity:["HKD","CNY"]
Settlement Cycle	Settlement cycle
Limit
Refund	refundValidity 180 days fullRefund partialRefund refundWay Original route refund
Tokenization	cardOnFile codeGrant networkToken
3DS
Capture
Recurring
Chargeback/Dispute
Integration Capabilities	Redirect Checkout OnePage Checkout Embedded SDK Element SDK API Only
remark	WeChat refund cannot be less than 0.01 CNY (including currency exchange situations)

Properties

支持的集成方式

Redirect to checkout

Redirect from your website to the hosted checkout page

Embedded checkout

Embed the checkout component on your website using JS-SDK

Server To Server

Use API for server-side interaction to fully customize your website's payment page.

WeChat Mini Program Payment

Within WeChat, use WeChat Mini Program for payment.

Payment Domain Authorization

According to WeChat requirements, the merchant's domain must be added to WeChat's H5 payment authorized domains. The Referer request header must also be set. We default to adding the domain from your account opening application to WeChat's H5 payment authorized domains.

If you need to add other domains, please send the relevant application information to acquire-risk@pingpongx.com and CC acquire-ts@pingpongx.com.

Application materials:

1. Merchant Client ID
2. Merchant authorized domain

Payment Scenario Description

PC Payment

• Display WeChat payment QR code
• Users complete payment by scanning QR code with WeChat
• Page displays real-time payment status updates

Mobile Payment

1. WeChat in-browser: Direct WeChat payment invocation is not currently supported, JSAPI call required per WeChat requirements.
2. Non-WeChat browsers:
   • iOS: Redirect to WeChat client
   • Android: Display QR code or attempt to invoke WeChat
   • Other cases: Display QR code for scan-to-pay

Note

• Your domain must be added to WeChat H5 payment authorized domains.
• WeChat has strict requirements for Referer, please ensure Referer request header is set.
• Ensure users access payment page through page redirection rather than direct access to payment link

Common Issues

Error message: "Merchant parameter format is incorrect, please contact merchant to resolve"

Problem cause:

• Referer request header is empty or missing
• User directly accesses payment link without page redirection

Solution:

1. Ensure users access payment page through page redirection rather than direct access to payment link
2. App WebView needs to manually set Referer request header:

   Map<String, String> extraHeaders = new HashMap<>();
   extraHeaders.put("Referer", "https://your-authorized-domain");

Error message: "Merchant has unconfigured parameters, please contact merchant to resolve"

Problem cause:

• Current webpage domain does not match H5 payment authorized domain configured in WeChat backend

Solution:

1. Contact us to confirm if authorized domain is correct
2. Modify or add correct authorized domain

Error message: "Payment request has expired, please initiate payment again"

Problem cause:

• Payment link exceeds 5-minute validity period

Solution:

• Re-call payment interface to generate new payment link

Error message: "Please open order in WeChat external browser to complete payment"

Problem cause:

• Using H5 payment method within WeChat client

Solution:

• Use JSAPI payment in WeChat environment
• Guide users to open payment page in external browser

Error message: "Signature verification failed" or "System busy"

Problem cause:

1. Multiple WeChat accounts accessing same payment link
2. Callback URL encoding is incorrect

Solution:

1. Generate independent payment link for each user
2. Ensure callback URL parameters are correctly encoded

Error message: "H5 transaction parameters passed by merchant are incorrect"

Problem cause:

• Client IP address is incorrect (such as using 127.0.0.1)

Solution:

• Use real client IP address

Referer Configuration Instructions

WeChat H5 payment has strict requirements for Referer (source domain in HTTP request header):

Referer function: WeChat server determines current webpage source domain through Referer header, checking if it matches H5 payment authorized domain configured in WeChat merchant platform.

Common Referer issue solutions:

Issue Type	Specific Manifestation	Solution
Referer empty	Direct access to payment link or WebView without Referer set	Ensure access through page redirection; WebView manually set Referer
Domain mismatch	Current domain does not match authorized domain	Add or modify authorized domain in WeChat merchant platform
WebView configuration	App H5 unable to invoke payment	Manually add Referer Header

Previous pageVNM QR

Next pageZIP