Log inGet started
Airwallex logo
Online Payments
Transactional FX
Open Banking
Developer Tools
API Reference
Online Payments
Starting with paymentsTransaction and settlement modelPricing model
Integration options
Integration OverviewPayment LinksPayment Links APIHosted Payment Page
Embedded ElementsDrop-in ElementMobile SDKNative APIPlugins

Hosted Payment Page

The Hosted Payment Page integration option redirects your shoppers to a secure, pre-built payment page hosted by Airwallex. It lets you accept multiple payment methods with a single integration. You do not have to worry about collecting or storing shopper’s payment details as Airwallex fully handles the payment processing thereby significantly reducing your PCI-DSS compliance costs.

Key features include:

  • Reduces friction for card payments with input validation, styling and error handling.
  • Responsive design to fit seamlessly on any screen size
  • Custom styling rules so you can match the look and feel of your site
  • Reduced PCI-DSS compliance handling costs – a PCI-DSS SAQ A is sufficient

How it works

The diagram below depicts the information flow in a Hosted Payment Page integration. HPP 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 if you want to offer alternative payment methods (Alipay, Dana, KakaoPay, etc) that redirect shoppers to a partner site. The shopper will be returned to the return_url after the payment is complete, 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.

To display order information on the Hosted Payment Page, provide the order object with the product information when you call Create a PaymentIntent API.


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 redirect button to your checkout page

To redirect your shopper to the Hosted Payment Page, you will need a checkout button and a button handler to trigger the redirect.

Add the checkout button


Add the button handler

Provide the intent_id and client_secret retrieved from Step 1, and the currency for the payment in the redirectToCheckout( ) method.


When this method is triggered, Airwallex will redirect your shopper to the Hosted Payment Page, display the relevant payment methods on the payment page, collect the shopper’s payment details, and eventually trigger the authentication.

Note that Hosted Payment Page automatically handles 3D Secure authentication, offering either frictionless or challenge flow depending on the card issuer’s requirements. For more information, see 3D Secure authentication .

You can also customize the Hosted Payment Page by providing options JS in the redirectToCheckout( ) method.

Step 4: Retrieve the payment result

Upon completing the payment, your shopper will be redirected to one of these URLs, successUrl , failUrl, cancelUrl, provided in redirectToCheckout( ) method, and the PaymentIntent id will be appended to the URL.


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

Use test card numbers and the test and go-live checklist to test your integration for various success and error scenarios in the demo environment and then go live in the production environment.

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 Hosted Payment Page integration.


You can configure the Hosted Payment Page to display localized text of the payment fields based on the locale set in redirectToCheckout(). For supported locales, see the locale property JS.

Save card details for future payments

Airwallex allows you to create a PaymentConsent with the shopper to initiate future payments using shopper’s saved card details. For more information, see Save payment details for future payments .


What are the common scenarios with a Hosted Payment Page integration?

Some common 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, https://checkout.airwallex.com/assets/elements.bundle.min.js 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.

What payment methods are supported in a Hosted Payment Page integration?

All payment methods configured on your merchant account are supported. The list displayed to the shopper on the payment form is filtered based on the following fields:

  • currency passed in redirectToCheckout()

  • components[] passed in redirectToCheckout() . Contains the list of payment methods you want to offer the shopper.

  • (Optional) country_code passed in redirectToCheckout() for payment methods such as online_banking, bank_transfer, seven_eleven, skrill, sofort, trustly, paysafecash, paysafecard, satispay, paysera, paypal, bitpay

How do I customize Hosted Payment Page?

You can provide the theme object in redirectToCheckout() to customize the font styles of the Hosted Payment Page. Airwallex supports two font weights: regular (400) and bold (700). You can specify font options using src, family and weight attributes.

Can I offer Apple Pay via Hosted Payment Page?

Yes, Apple Pay is supported via Hosted Payment Page integration. Ensure that your merchant account is enabled for Apple Pay on the Airwallex web app > Payments > Settings. For more information, see Enable Apple Pay. Once registered, you can pass applePayRequestOptions JS in redirectToCheckout to offer Apple Pay. Note that countryCode is mandatory.


Can I offer Google Pay via Hosted Payment Page?

Yes, Google Pay is supported via Hosted Payment Page integration. Ensure that your merchant account is enabled for Google Pay on the Airwallex web app > Payments > Settings. For more information, see Enable Google Pay. Once registered, you can pass googlePayRequestOptions JS in redirectToCheckout to offer Google Pay. Note that countryCode is mandatory.

On this page