Log inGet started
Airwallex logo
Home
Online Payments
Treasury
Transactional FX
Payouts
Issuing
Scale
Open Banking
Developer Tools
API Reference
Home
Online Payments
Overview
Starting with paymentsAirwallex platform overviewOnline payments modelPricing model
Integration options
Pay by LinkHosted Payment PageEmbedded Elements
Card ElementSplit Card Element
Full Featured Card ElementRedirect ElementQR Code ElementWeChat Pay ElementApple Pay ElementGoogle Pay Element
Drop-in ElementMobile SDKNative APIPlugins

Split Card Element

The Split Card Element allows you to embed individual input fields (card number, expiry, CVC) on your checkout page to securely collect card details and submit these details to Airwallex to make a payment. In comparison to Card Element and Full Featured Card Element , it provides greater control over the look and feel of the checkout page.

This page describes how to embed a Split Card Element on your payment page to accept payments.

How it works

The diagram below depicts the information flow in a Split Card Elements integration. Split Card Element 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.

curl --request POST \
--url 'https://api-demo.airwallex.com/api/v1/pa/payment_intents/create' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer <your_bearer_token>' \
--data-raw '{
    "request_id": "00e8df19-7087-4209-b50b-067d6a39ee72",
    "amount": 100,
    "currency": "CNY",
    "merchant_order_id": "Merchant_Order_a7f9baf8-884a-4def-ba85-d1f9be83470a",   
    "return_url": "http://www.merchant.com/result"
}' 

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 Split Card Elements to your checkout page

To embed the Split Card Elements into your checkout page, you will need to create an empty container, create the Elements and then mount the Elements to the container.

Define the payment form

First, create an empty container div with a unique id in your payment form and a Submit button to trigger the payment request. Ensure that the payment form only contains one Element with this unique id. Airwallex inserts an iframe into this div that securely collects card information.

  <!-- Add empty containers for each card input element  -->
      <div style={containerStyle}>
        <div>Card number</div>
        <div id="cardNumber"></div>
      </div>
      <div style={containerStyle}>
        <div>Expiry</div>
        <div id="expiry"></div>
      </div>
      <div style={containerStyle}>
        <div>CVC</div>
        <div id="cvc"></div>
    </div>
    <br />
    <!-- Add a submit button to trigger the payment request -->
    <button id="submit">Submit</button>

Create the Split Card Elements

When the payment form has loaded, call createElement(type, options) by specifying the Element type as cardNumber, expiry, and cvc respectively to create card number, expiry date, and CVC Elements. Ensure that the payment form only contains one Element with these ids.

// Create split card elements
      const cardNumber = Airwallex.createElement('cardNumber');
      const expiry = Airwallex.createElement('expiry');
      const cvc = Airwallex.createElement('cvc');

Mount the Split Card Elements

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

      // Mount split card elements
      cardNumber.mount('cardNumber'); // Injects iframe into the Card Number Element container
      expiry.mount('expiry'); // Injects iframe into the Expiry Element container
      cvc.mount('cvc'); // Injects iframe into the CVC Element container

Optionally, you can provide the PaymentIntent id and client_secret in createElement() or create a PaymentIntent after the shopper clicks the Submit button and pass the details in confirmPaymentIntent().

// Create split card elements
      const cardNumber = Airwallex.createElement('cardNumber', {
    id: 'replace-with-your-intent-id',
    client_secret: 'replace-with-your-client-secret',
});
      const expiry = Airwallex.createElement('expiry');
      const cvc = Airwallex.createElement('cvc');

Split Card props

You can also pass options in createElement() to overwrite styles and other functions as shown in the following table. All properties are optional. For details, see cardNumber, expiry, CVC props JS.

Step 4: Confirm the PaymentIntent

When the shopper clicks the Submit button, call confirmPaymentIntent() by passing the Element, id and client_secret returned in Create a PaymentIntent, to complete the payment.

Airwallex.confirmPaymentIntent(options);

You can also pass options in confirmPaymentIntent() depending on your payment flow. For details, see confirmPaymentIntent props JS.

Handle the submit event

Add an event handler to the Submit button and listen to the form’s submit event to know when to confirm the payment.

document.getElementById('submit').addEventListener('click', () => {
  Airwallex.confirmPaymentIntent({
    element: cardNumber, // Provide the cardNumber element for Split Card, card element for Card
    id: 'replace-with-your-intent-id', // Payment Intent ID
    client_secret: 'replace-with-your-client-secret', // Client Secret
  }).then((response) => {
    // STEP #6b: Listen to the payment confirmation response
    /* Handle response */
    window.alert(JSON.stringify(response));
  });
});

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

 window.addEventListener('onReady', (event) => {
        /*
        ... Handle event
         */
        window.alert(event.detail);
      });

Add onChange event listener to help your shopper catch mistakes in the input fields. Use this to validate the fields and display errors before the shopper clicks the Submit button.

window.addEventListener('onChange', (event) => {
  /*
    ... Handle event
  */
  window.alert(event.detail);
});

Step 5: Handle the response

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

const element = mount('root');
element.addEventListener('onSuccess', (event) => {
  // Handle event on success
});

element.addEventListener('onError’, (event) => {
  // Handle event on error
});

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

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 Embedded Element integration.

Localization

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

  • en (US English)
  • zh (Simplified Chinese)
  • ja (Japanese)
  • ko (Korean)
  • ar (Arabic)
  • fr (French)

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 .

3D Secure authentication

Airwallex automatically handles 3D Secure authentication offering either frictionless or challenge flow depending on the card issuer’s requirements. You can optionally pass the following fields in createElement( ) to support 3DS:

  • authFormContainer: A container for the authentication form. If a challenge flow is required to authenticate the shopper, an iframe will be rendered in this container to display the authentication page provided by the issuing bank. If not provided, Airwallex will create a div after body tag and use it as the container.
  • withBilling: If applicable set this to true to collect billing information from the shopper, which increases the likelihood of frictionless checkout.

FAQ

What are the common error scenarios with Embedded Elements 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.

How do I customize the Embedded Element?

You can provide the fonts[ ] option in init( ) or loadAirwallex( ) when you initialize Airwallex to customize the font styles of payment Elements. Airwallex supports two font weights: regular (400) and bold (700).  You can specify font options using src, family and weight attributes.

fonts: [
         {
           src: 'https://checkout.airwallex.com/fonts/CircularXXWeb/CircularXXWeb-Regular.woff2',
           family: 'AxLLCircular',
           weight: '400',
         },
         {
           src: 'https://checkout.airwallex.com/fonts/CircularXXWeb/CircularXXSub-BoldSubset.woff2',
           family: 'AxLLCircular',
           weight: '700',
         },
       ],

You can also customize styles for the cardNumber/card/fullFeaturedCard Element using style. With Split Card, you can also customize cvc and expiry Elements.

  <style>
    #dropIn {
      width: 540px;
      /* Example: to hide element before it is loaded */
      display: none;
    }
  </style>

How do I display the cardholder name field for a Card/Split Card Element?

You can render a Cardholder Name input field on your checkout page alongside the Card/Split Card Elements. The cardholder name is not mandatory to confirm and complete a payment.

On this page