Learn about WeChat Pay, a digital wallet popular with customers from China. #
WeChat Pay serves as a digital wallet integrated into the popular Chinese superapp known as WeChat. Over the years, it has gained significant prominence as an essential payment solution for businesses seeking to connect with Chinese consumers, both domestically and internationally. WeChat has transformed into a comprehensive ecosystem, offering Chinese shoppers the convenience of chatting, browsing products or services, and making payments seamlessly within a unified platform. This integration has made the shopping experience as effortless as having a friendly conversation with your companions, all in one place.
Features #
| Customer locations | Chinese consumers Overseas Chinese Chinese travelers |
|---|---|
| Processing currencies | CNY, GBP, USD, EUR, HKD |
| Settlement currencies | GBP, EUR, USD, HKD |
| Minimum transaction amount | No limit |
| Maximum transaction amount | 50,000 USD |
| Refunds | ✅ |
| Partial Refunds | ✅ |
| Multiple partial refund | ✅ |
| Chargeback | ❌ |
Subproducts #
| Payment case | Product | Payment scenarios description |
|---|---|---|
| QR Code | Web Payment | On Desktop browser, after selecting WeChatPay as a payment method merchant checkout, a QR code appears. The shopper then opens WeChat app on their mobile phone and scans the barcode displayed on the browser page to complete the payment. |
| QR Code | Quick Pay | On point of sale, Merchants can display the QR code on the terminal and shoppers can open their WeChat app on their mobile phones to scan the QR code to complete payment. |
| Mobile H5 Flows | H5 payment | On the mobile browser, a shopper selects WeChatPay as a payment method on Merchant checkout, and as redirected from the browser into the WeChatPay app to complete the payment before being redirected back to the Merchant browser. |
| Mobile – In WeChat app | Official Account | Usually popular in more Chinese speaking markets, Merchants can consider building a profile page on the WeChat social site and prompt shoppers to select products and complete payment within the WeChat social site environment. |
| Mobile – In WeChat app | Mini Program | Another spin on Official Accounts, a Mini Program is like a website within the WeChat social site where more customizations from the Merchant are possible and shoppers can select products and complete payment within that environment. |
Payment Flow #
QR Code #
Mobile H5 Flows #
Mobile – In WeChat app #
Integration Method #
Payment method enumeration values: wechat_pay
There are two integration methods for Wechat pay
- Direct API
- Checkout
| Integration method | Wechat Pay subproduction | terminal_type enumeration values |
|---|---|---|
| Direct API | Web Payment | WEB |
| Direct API | Quick Pay | SCAN_CODE |
| Direct API | H5 Payment | WAP |
| Direct API | Official Account Payment | OFFICIAL_ACCOUNT |
| Direct API | Mini Program | MINI_PROGRAM |
| Integration method | Wechat Pay subproduction | terminal_type enumeration values |
|---|---|---|
| Checkout | Web Payment | You don’t need to identify the terminal type in checkout. Checkout will automatically generate a QR code or redirect to WeChat App based on their device. |
| Checkout | H5 Payment | You don’t need to identify the terminal type in checkout. Checkout will automatically generate a QR code or redirect to WeChat App based on their device. |
Direct API #
A PaymentIntent is an object that represents your intent to collect payment from your customer and tracks the lifecycle of the payment process. Create a PaymentIntent on your server and specify the amount to collect and a supported currency.
Create a PaymentIntent #
For direct API integration, you can create PaymentIntent and get url in only one step. The following is the demo of creating payment intents:
- Web Payment
- H5 Payment
- Quick Pay
- Official Account Payment
Web Payment #
Request
{
"amount":20,
"currency":"CNY",
"confirm":true,
"payment_method_options":{
"wechat_pay":{
"terminal_type":"WEB",
"os_type":"IOS",
"client_ip":"192.168.0.1"
}
},
"payment_method_data":{
"type":"wechat_pay"
},
"return_url":"https://wooshpay.com"
}Response
{
"id": "pi_1666625039547498496",
"object": "payment_intent",
"created": 1686189348000,
"livemode": false,
"currency": "CNY",
"amount": 20,
"status": "requires_action",
"client_secret": "pi_1666625039547498496_secret_qGj2VEg4khXSWkXvRI7Y3yZe",
"next_action": {
"type": "wechat_pay_display_qr_code",
"wechat_pay_display_qr_code": {
"image_data_url": "weixin://wxpay/bizpayurl?pr=lJhTByDzz"
}
},
"payment_method_types": [
"wechat_pay",
],
"confirmation_method": "automatic",
"payment_method_options": {
"wechat_pay": {
"terminal_type": "WEB",
"os_type": "IOS",
"client_ip": "192.168.0.1"
}
},
"return_url": "https://wooshpay.com",
"payment_method": "pm_1666625039430057984",
"capture_method": "automatic"
}The image_data_url from wechat_pay_display_qr_code from next_action can be opened, from the link, the merchant can generate corresponding QR codes. Then use the corresponding QR code to charge.
H5 Payment #
Request
{
"amount": 20,
"currency": "CNY",
"confirm": true,
"payment_method_options": {
"wechat_pay": {
"terminal_type": "WAP",
"client_ip": "192.168.124.133" //customer's mobile's ip
}
},
"payment_method_data": {
"type": "wechat_pay"
},
"return_url": "yourwebsite"
}Response
{
"id": "pi_1666625208749916160",
"object": "payment_intent",
"created": 1686189389000,
"livemode": false,
"currency": "CNY",
"amount": 20,
"status": "requires_action",
"client_secret": "pi_1666625208749916160_secret_BeEXcbvAQNUkrV9C6ZFjOamS",
"next_action": {
"type": "wechat_pay_redirect_to_web",
"wechat_pay_redirect_to_web": {
"url": "https://wx.tenpay.com/cgi-bin/mmpayweb-bin/checkmweb?prepay_id=wx08095629694611f41b32df91d6ea160000&package=3449031350&redirect_url=https%3A%2F%2Fwooshpay.com"
}
},
"payment_method_types": [
"wechat_pay"
],
"confirmation_method": "automatic",
"payment_method_options": {
"wechat_pay": {
"terminal_type": "WAP",
"os_type": "IOS",
"client_ip": "172.31.5.62"
}
},
"return_url": "https://wooshpay.com",
"payment_method": "pm_1666625208624087040",
"capture_method": "automatic"
}The url from wechat_pay_redirect_to_web from next_action can be opened, from the link, the customer will be direct to the wechat APP for payment, and be direct to return_url after payment.
Quick Pay #
Request
{
"amount":10,
"currency":"CNY",
"confirm":true,
"payment_method_options":{
"wechat_pay":{
"terminal_type":"SCAN_CODE",
"os_type":"IOS",
"client_ip":"192.168.0.1"
}
},
"payment_method_data":{
"type":"wechat_pay",
"wechat_pay":{
"payment_code":"132993614656096754"
}
},
"return_url":"https://yourweb.com"
}Response
{
"id": "pi_1666627489012645888",
"object": "payment_intent",
"created": 1686189932000,
"livemode": false,
"currency": "CNY",
"amount": 10,
"status": "requires_action",
"client_secret": "pi_1666627489012645888_secret_t6oeKYYGb9egt3koNMsntfSg",
"payment_method_types": [
"wechat_pay"
],
"confirmation_method": "automatic",
"payment_method_options": {
"wechat_pay": {
"terminal_type": "SCAN_CODE",
"os_type": "IOS",
"client_ip": "192.168.0.1"
}
},
"return_url": "https://yourweb.com",
"payment_method": "pm_1666627488878428160",
"capture_method": "automatic"
}The password-free payment can be paid directly, otherwise the customer needs to enter the password, fingerprint, etc. on the mobile phone to pay.
Official Account Payment #
Request
{
"amount": 20,
"currency": "CNY",
"confirm": true,
"payment_method_options": {
"wechat_pay": {
"terminal_type": "OFFICIAL_ACCOUNT",
"client_ip": "192.168.0.1",
"openid": ""
}
},
"payment_method_data": {
"type": "wechat_pay"
}
}Response
{
"id": "pi_1666626536515567616",
"object": "payment_intent",
"created": 1686189705000,
"livemode": false,
"currency": "CNY",
"amount": 20,
"status": "requires_payment_method",
"client_secret": "pi_1666626536515567616_secret_CcrukFKgxbPp7UEAxodLlNRD",
"last_payment_error": {
"code": "payment_method_provider_decline",
"message": "service error. Please try it again.",
"payment_method": {
"id": "pm_1666626536389738496",
"object": "payment_method",
"created": 1686189705000,
"livemode": false,
"type": "wechat_pay",
"billing_details": {}
},
"decline_code": "invalid_request_error"
},
"payment_method_types": [
"wechat_pay"
],
"confirmation_method": "automatic",
"payment_method_options": {
"wechat_pay": {
"openid": "",
"terminal_type": "OFFICIAL_ACCOUNT",
"client_ip": "192.168.0.1"
}
},
"payment_method": "pm_1666626536389738496",
"capture_method": "automatic"
}wechat_pay_official_account_params from next_action contains some parameters you need to use in the front end. Below is an example on how to use the parameters. js example
function onBridgeReady(){
WeixinJSBridge.invoke(
'getBrandWCPayRequest', {
"appId":"wx7a154c094f74e84f",
"timeStamp":"1682239457",
"nonceStr":"kLRl3fI6FiP8PXxNNAiytwuQBdoCWXvZ",
"package":"prepay_id=wx23164417189051acf8825c57d275230000",
"signType":"MD5",
"paySign":"703868ed93842f83c9dff4d80d0cad67"
},
function(res){
if(res.err_msg == "get_brand_wcpay_request:ok" ) {} // Using the above method to judge the front-end return, the WeChat team solemnly reminds: res.err_msg will return ok after the user's payment is successful, but it does not guarantee that it is absolutely reliable.
}
);
}
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();
} Mini Program #
Request
{
"amount": 20,
"currency": "GBP",
"confirm": true,
"payment_method_options": {
"wechat_pay": {
"terminal_type": "MINI_PROGRAM",
"client_ip": "192.168.0.1",
"openid": "ojt**********QnCY"
}
},
"payment_method_data": {
"type": "wechat_pay"
}
}Response
{
"id": "pi_1684807723566235648",
"object": "payment_intent",
"created": 1690524438000,
"livemode": true,
"currency": "GBP",
"amount": 20,
"status": "requires_action",
"client_secret": "pi_1684807723566235648_secret_V3rhLjnidzwNnc7UomZJzzxc",
"next_action": {
"type": "wechat_pay_mini_program_params",
"wechat_pay_mini_program_params": {
"appId": "***********",
"timeStamp": "1690524439",
"nonceStr": "VVdQaFzG9LjOSNyGNLFbt7NZAn2oE87z",
"signType": "MD5",
"paySign": "9d0a90a35935d71d7a0f5f33689030fe",
"package": "prepay_id=wx281407195596079e2b5253415099630000"
}
},
"payment_method_types": [
"wechat_pay",
],
"confirmation_method": "automatic",
"payment_method_options": {
"wechat_pay": {
"openid": "**********",
"terminal_type": "MINI_PROGRAM",
"client_ip": "192.168.0.1"
}
},
"payment_method": "pm_1684807723448795136",
"capture_method": "automatic"
}Checkout #
You can also utilize WeChat Pay via checkout hosted by WooshPay. To support payments, a Checkout Session must satisfy all of the following conditions:
- Prices for all line items must be in the same currency. If you have line items in different currencies, create separate Checkout Sessions for each currency.
- You can only use one-time line items.
Enable wechat pay as a payment method
When creating a new Checkout Session, you need to:
Add Wechat Pay to the list of payment_method_types. Make sure all line_items use the same currency.
Create a Session #
Request
{
"cancel_url": "https://wooshpay.com",
"mode": "payment",
"success_url": "https://wooshpay.com",
"payment_method_types": [
"wechat_pay"
],
"line_items": [
{
"price_data": {
"currency": "CNY",
"unit_amount": 100,
"product_data": {
"name": "fengli",
"url": "www.baidu.com"
}
},
"quantity": 1
}
]
}Response
{
"id": "cs_1666627733867724800",
"object": "checkout.session",
"created": 1686189991000,
"livemode": false,
"currency": "CNY",
"customer": "",
"mode": "payment",
"status": "open",
"url": "https://checkouttest.wooshpay.com/pay/cs_test_1666627733867724800?key=pk_test_NTE1OTU5NzQ3NTQ2MTM5ODkzNzcxOktFZ0xlam1KbUxUb2gyUUNqWVVoaGpDSjE2NjkzNDUwMDgxMTE=",
"cancel_url": "https://wooshpay.com",
"line_items": {
"object": "list",
"data": [
{
"id": "li_1666627733993553920",
"object": "item",
"currency": "CNY",
"description": "fengli",
"price": {
"id": "price_1666627734022914048",
"object": "price",
"created": 1686189991000,
"livemode": false,
"active": true,
"currency": "CNY",
"product": {
"id": "prod_1666627734064857088",
"object": "product",
"created": 1686189991000,
"livemode": false,
"active": true,
"name": "fengli",
"url": "www.baidu.com",
"updated": 1686189991000
},
"type": "one_time",
"unit_amount": 100,
"billing_scheme": "per_unit"
},
"quantity": 1,
"amount_subtotal": 100,
"amount_total": 100
}
]
},
"payment_intent": "pi_1666627734450733056",
"payment_method_types": [
"wechat_pay"
],
"payment_status": "unpaid",
"success_url": "https://wooshpay.com",
"amount_subtotal": 100,
"amount_total": 100,
"billing_address_collection": "auto",
"expires_at": 1686276390865,
"payment_link": "",
"client_secret": "pi_1666627734450733056_secret_jajX5Fe4Qlp6VGEm0ftP1wcZ"
}You can access the checkout counter through the url, and select WeChat payment. If the client is a web page, it will generate a QR code and you can scan the code for payment. If the client is a mobile terminal, it will directly jump to the WeChat APP for payment.
Next step #
You can add more features to your integration as needed
Create a Webhook #
Listen to events on your WooshPay account so your integration can automatically trigger reactions. Create a webhook that mainly focuses on enabled_events and url.
Create a Refund #
Create a refund to repay funds to your customer. You can also perform partial refunds, but not every payment method supports them. A partial refund is when you refund only part of the original transaction amount.
