Airwallex logo

Hosted Payment Page integration

The Hosted Payment Page integration enables Merchants to accept payments when they wish to delegate the full handling of the payment processing and display of the payment options. This integration will also support you when you do not have a full PCI-DSS certification and you can only fulfill a PCI-DSS SAQ.

The following steps will guide you through our integrations. Refer to our API reference for the complete details of the calls.

  1. Initially you need to create a Payment Intent. The payment intent captures the details of your checkout and includes the currency and amount you wish to charge your customer.
curl https://pci-api.airwallex.com/api/v1/pa/payment_intents/create \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer your_bearer_token \
  -d '{
    "request_id": "ed11e38a-7234-11ea-aa94-7fd44ffd1b89",
    "amount": 100,
    "currency": "CNY",
    "merchant_order_id": "85d7b0e0-7235-11ea-862e-9f6aa1adfca6"
  }'

The response of the Payment Intent creation looks as below and contains a client_secret, it represents your payment session and you need to use it to request the URL where you will redirect your client

{
    "id": "int_gECH4yeBzr50vOYFtzNyIsSW9e8",
    "request_id": "ed11e38a-7234-11ea-aa94-7fd44ffd1b89",
    "amount": 100.0,
    "currency": "CNY",
    "merchant_order_id": "85d7b0e0-7235-11ea-862e-9f6aa1adfca6",
    "status": "REQUIRES_PAYMENT_METHOD",
    "captured_amount": 0,
    "created_at": "2020-06-21T05:23:25+0000",
    "updated_at": "2020-06-21T05:23:25+0000",
    "available_payment_method_types": [
        "card",
        "wechatpay"
    ],
    "client_secret": "a_client_secret"
}
  1. Request the HPP link by leveraging the client_secret you obtained and the additional parameters of your checkout. At this stage you can customize the look and feel and how the page will be displayed. Note that the successUrl, failUrl and cancelUrl can be provided at this stage and will help you to control the flow post payment or in case of customer drop-off.

From this point Airwallex will take care of redirecting your customer, helping your customer to select the most appropriate payment method, collecting its payment details and eventually trigger the authentication. You need to do nothing.

Leverage the below interface to provide the appropriate parameters to the HPP system

/**
* Global font option config for Airwallex integration methods
*/
export interface FontOptions {
 /**
  * The font-family property
  * https://developer.mozilla.org/en-US/docs/Web/CSS/font-family
  */
 family?: string;
 /**
  * The font source url
  * https://developer.mozilla.org/en-US/docs/Web/CSS/@font-face
  */
 src?: string;
 /**
  * The font-weight property
  * https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight
  */
 weight?: string | number;
}
/**
* Indicate which airwallex integration env your merchant site would like to connect with
*/
export type AirwallexEnv = 'dev' | 'preview' | 'qa' | 'staging' | 'demo' | 'prod';
/**
* Config option for Hosted Payment Page(HPP) when doing redirect checkout using Airwallex payment page
*/
export interface HostPaymentPage {
 /**
  * Indicate which airwallex integration env your merchant site would like to connect with
  * If not provide default will be prod which point to [Airwallex Checkout](https://checkout.airwallex.com)
  */
 env?: AirwallexEnv;
 /**
  * The intent id you shopper want to checkout
  */
 id: string;
 /**
  * The client_secret when you create payment intent, contain in the response
  */
 client_secret: string;
 /**
  * Option with limited support for HPP page style customization
  */
 theme?: Style & FontOptions;
 /**
  * Checkout for know customer, refer to [Airwallex Client API](https://www.airwallex.com/docs/api#/Payment_Acceptance/Customers/Intro)
  */
 customer_id?: string;
 /**
  * The payment method component your website would like to integrate with
  */
 component?: 'default' | 'cards' | 'wechatpay';
 /**
  * Only support for card payment, indicate whether to capture immediate when authentication success
  */
 autoCapture?: boolean;
 /**
  * The success return url after shopper succeeded the payment
  */
 successUrl?: string;
 /**
  * The failed return url when shopper can not fulfill the payment intent
  */
 failUrl?: string;
 /**
  * The cancel return url when shopper canceled the payment intent
  */
 cancelUrl?: string;
 /**
  * The logo url of your website you want to show in the HPP head
  */
 logoUrl?: string;
 /**
  * i18n localization config
  */
 locale?: 'en' | 'zh';
 /**
  * Apply only for card, to improve 3DS experience, indicate if the payment form will collect billing info from shopper
  */
 withBilling?: boolean;
}

Initialize the airwallex javascript context in your webpage with below script tag:

<!-- Step #1: Load Checkout Universal Module Definition (UMD) bundle js-->
<script src="https://checkout.airwallex.com/assets/bundle.0.0.xx.min.js"></script>

Then leverage the parameters through the interface and call the below function on your webpage after payment intent is created

// Step #2: Call the HPP function to checkout
Airwallex.redirectToCheckout({
 env: 'demo', // Which env('staging' | 'demo' | 'prod') you would like to integrate with
 id: 'replace-with-your-intent-id',
 client_secret: 'replace-with-your-client-secret'
});

Upon this call the customer will be automatically redirected and we will take care of the encoding of the URL. The below URLS are samples and it is where your customer will be redirected.

Redirect to the successUrl / FailUrl / cancelUrl with merchant provided links

https://demo-pacheckoutdemo.airwallex.com/checkout-fail?id=int_dN2QSTjmzcqXNhQn5zQpvEJud6M
  1. Upon completion your customer will be redirected to the successUrl or failUrl you provided in the previous step. You will obtain the final status of your payment through your notifications, the payment success notification will be sent to the endpoint you have configured.

The return success URL will be appended with the success payment intent.

https://demo-pacheckoutdemo.airwallex.com/checkout-success?id=int_dN2QSTjmzcqXNhQn5zQpvEJud6M