Log inGet started
Airwallex logo
Core API
Transactional FX
Back to home
OverviewChoose your payments solutionGet started with payments
Online payments
Invoice integrations
Payment methods
Payment methods overviewGlobal
Alipay HK
DOKU Wallet
E.SUN (Taiwan ATM & Internet banking)
GrabPay - Malaysia
GrabPay - Singapore
Indonesian Bank Transfer
Indonesian Convenience Stores
Jenius Pay
Kakao Pay
Kiosk Payments
Philippines Online Banking
Rabbit LINE Pay
Taiwan Convenience Stores
Tesco Lotus
Thailand Online Banking
Touch 'n Go
WeChat Pay
Website QRWeChat Pay Element
Mobile App Mobile Browser (H5)WeChat Official AccountWeChat Mini Program Customs Declaration WeChat Pay funds split

WeChat Pay Element

The WeChat Pay Element allows you to embed a WeChat Pay QR code checkout option on your payment page. It contains a QR code that matches the specified PaymentIntent and a Refresh button to regenerate the QR code. The shopper can scan the QR code using their WeChat app to make a payment.

This page describes how to embed a WeChat Pay Element on your payment page to accept payments.

How it works

The diagram below depicts the information flow in a WeChat Pay QR Code Element integration. WeChat Pay sequence

Before you begin

Before you implement the integration, consider the following:

Step 1: Set up the server to create a PaymentIntent

When the shopper begins the checkout process, you will need to create a PaymentIntent object to indicate your intent to collect payment from the shopper.

When the checkout page loads, on your server, call Create a PaymentIntent API API with an amount and currency. Always decide how much to charge on the server side, a trusted environment, as opposed to the client. This prevents malicious shoppers from being able to alter the payment amount.

Provide return_url in Create a PaymentIntent API to indicate where Airwallex should redirect the shopper after completing the payment, whether successful or otherwise.

The PaymentIntent’s id and client_secret are returned in the response these parameters let you confirm the payment and update card details on the client, without allowing manipulation of sensitive information, like payment amount.


Step 2: Initialize Airwallex on your checkout page

First, you will need to import the airwallex-payment-elements SDK and then initialize the package. For details, see Initialize Airwallex JS.

Step 3: Add the WeChat QR Code Element to your checkout page

To embed the WeChat QR Code Element into your checkout page, you will need to create an empty container, create the Element and then mount the Element to the container.

Define the payment form

First, create an empty container div with a unique id in your payment form. Ensure that the payment form only contains one Element with this unique id. Airwallex inserts an iframe into this div on mounting the Element.


Create the WeChat QR Code Element

When the payment form has loaded, call createElement(type, options) by specifying the Element type as wechat to create the Element. Ensure that the payment form only contains one Element with wechat id. Passing PaymentIntent id and client_secret as options is mandatory.


Mount the WeChat QR Code Element

Call mount() with the id of the div to mount the Element to the DOM. The Element should only be mounted once in a single payment flow.


Add onReady event listener to ensure the Element is mounted. Use this event to prepare and load the checkout page.


Step 4: Handle the response

Add onSuccess and onError event listeners to handle error and success events received from Airwallex.


If no error occurred, display a message that the payment was successful. If payment fails with an error, display the appropriate message to your shopper so they can take action and try again.

Retrieve the payment result

For any actions subsequent to the payment such as shipping goods or sending email receipts, you can retrieve the payment result using the following options:

  • Set up webhooks to receive notifications on whether the payment has succeeded. Airwallex sends payment_intent.succeeded event when a payment succeeds. Listen to these events rather than waiting on a callback from the client. On the client, the shopper could close the browser window or quit the app before the callback executes. For information on how to set up webhooks and listen to events, see Getting started with webhooks

  • On your server, call Retrieve a PaymentIntent API to check the PaymentIntent status.

  • Check Payment Activity screen on your Airwallex web app.

Test your integration

Perform transaction tests in the production environment as described in the go-live checklist to ensure your integration is working correctly.

Example integrations

Explore a full, working code sample of an integration built using various web frameworks JS.

Additional features

You can add the following features to your Embedded Element integration.


You can configure the Element to display localized text of the payment fields based on the locale set in init() or loadAirwallex( ). See supported locales JS.

Device fingerprinting

Device fingerprinting uniquely tracks and identifies devices used for transacting on your shopping site, increasing your protection from fraud. The airwallex-payment-elements JavaScript client library automatically handles device fingerprinting, so no additional integration is needed.


What are the common error scenarios with Embedded Elements integration?

Some common error scenarios include :

ErrorNext steps
Airwallex is not definedCheck if you have initialized Airwallex (Step 2) before using Airwallex functions. If you are using CDN, check if you have changed the bundle version from x.x.x to the latest version in the package.json file. For example, is invalid
Access denied, authentication failedCheck if you have replaced your intent id and client_secret in createElement() and optionally confirmPaymentIntent().
The PaymentIntent with ID int_xxxxxxxxx cannot be foundCheck if the environment you initialized Airwallex in, for example, demo or prod, matches the environment you retrieved your intent id and client_secret from. In other words, if you ran init in the demo environment, you must also create your PaymentIntent in the demo environment.
InvalidAccessError: Page already has an active payment sessionApplePay doesn't allow duplicate sessions in the same page. However, you may create the apple pay element multiple times, please follow either of the options listed to address the error: 1) Call the destroy function to destroy old element before you create the new element. 2) Call the update function to update the old element with new intentId.
On this page