Wechat Pay

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

pic_QR Code.png

Mobile H5 Flows

pic_Mobile H5 Flows.png

Mobile - In WeChat app

pic_Mobile - In WeChat app.png

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
Mini Program

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": "ojt**********QnCY" 
        }
    },
    "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",
    "next_action": {
        "type": "wechat_pay_mini_program_params",
        "wechat_pay_official_account_params": {
            "appId": "XXXXXXXXXXX",
            "timeStamp": "1710404474",
            "nonceStr": "cqpXTO3D1XL5hDapG8JVMbzfEJKcRwAc",
            "signType": "MD5",
            "paySign": "XXXXXXXXXXX",
            "package": "prepay_id=XXXXXXXXXX"
        }
    },
    "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.

Last modified: 8 个月前