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
Features
3D Secure authenticationSave payment details for future payments
Hosted Payment PageEmbedded Elements
Redirect/QR Code ElementDrop-in ElementMobile SDKNative API
Fraud managementRiskDisputesMulti-currency pricingNetwork Tokenization

Embedded Elements

Embedded Elements integration allows you to save payment details for future payments . To save card details, Airwallex allows you to create a PaymentConsent, which represents the consent between you and the shopper to use the shopper’s saved card details for future payments. To make a subsequent payment, you simply must provide the id of the PaymentConsent when you confirm the PaymentIntent.

PaymentConsents may be used to trigger different payment scenarios:

  • Customer-initiated subsequent payments: This is useful for recurring shoppers who can make payments by selecting the saved card and optionally enter their security code (CVC) for verification to complete the payment.

  • Merchant-initiated subsequent payments: You as a merchant can initiate scheduled (recurring) or unscheduled (one-time) payments without the shopper involved.

This page describes how to save card details using Card/Split Card Element integrations. For Drop-in/Full Featured Card/Redirect/QR Code Element integrations, Airwallex handles the PaymentConsent creation automatically. For details, see:

Before you begin

Before you implement the integration, consider the following:

Create a PaymentConsent

You can choose to create and verify a PaymentConsent using createPaymentConsent() when the shopper creates an account with your business or when the shopper makes a payment for the first time.

createPaymentConsent(props);

For details on the options you can provide in createPaymentConsent(), see createPaymentConsent props JS.

Save card details without a payment

You can save a shopper’s payment method without an initial payment and charge the shopper later. This is helpful if you want to first onboard shoppers, save their payment details, and then initiate payments (recurring or one-time) in the future without the shopper involved.

This integration is also helpful to the shopper to make future payments using saved payment details.

Step 1: Create a Customer

To set a card up for future payments, you must first store the card on a Customer object. Create a Customer object using Create a Customer API API when your shopper creates an account with your business. You can also store name, email and other details on the Customer. The response will contain a unique id for the shopper.

Step 2: Generate a client secret for the Customer

Provide the Customer id in Generate a client secret for a Customer API API and save the returned client_secret

Step 3: Create your checkout page

Create a checkout page with Embedded Card / Split Card Element to collect payment details.

Step 4: Create a PaymentConsent

When the shopper is ready to create a consent, call createPaymentConsent( ) by passing the client_secret from Step 2 and the required fields. Airwallex verifies the PaymentConsent and returns a unique PaymentConsent id that you can use in confirmPaymentIntent( ) when you make subsequent payments.

// Add a button handler
document.getElementById('submit').addEventListener('click', () => {
  Airwallex.createPaymentConsent({
    customer_id: 'replace-with-your-customer-id', // customer id
    client_secret: 'replace-with-your-client-secret', // Customer client secret
    currency: 'replace-with-your-currency', // currency
    element: cardElement // card element or cardNumber element depends on your integration
    next_triggered_by: 'customer' // 'merchant' for MIT and 'customer' for CIT
  }).then((response) => {
    // Listen to the request response
    /* Handle response */
    window.alert(JSON.stringify(response));
  });
});

Save card details during payment

You can save shopper’s payment details from a purchase. Some scenarios include saving payment details for future payments with the shopper or to initiate the first payment of a series of recurring payments.

Step 1: Create a Customer

To set a card up for future payments, you must first store the card on a Customer object. Create a Customer object using Create a Customer API API when your shopper creates an account with your business. You can also store name, email and other details on the Customer. The response will contain a unique id for the shopper.

Step 2: Create a PaymentIntent

Call Create a PaymentIntent API API by providing the amount, currency, and id of the shopper in the customer_id parameter. Save the returned intent id and client_secret.

Step 3: Create your checkout page

Create a checkout page with Embedded Card / Split Card Element to collect payment details.

Step 4: Create a PaymentConsent

When the shopper is ready to create a consent, call createPaymentConsent( ) by passing the intent_id and client_secret of the PaymentIntent. Save the returned unique PaymentConsent id for subsequent payments.

// Add a button handler
document.getElementById('submit').addEventListener('click', () => {
  Airwallex.createPaymentConsent({
    intent_id: 'replace-with-your-intent-id', // PaymentIntent id
    customer_id: 'replace-with-your-customer-id', // Customer id
    client_secret: 'replace-with-your-client-secret', // PaymentIntent client secret
    currency: 'replace-with-your-currency', // currency
    element: cardElement // card element or cardNumber element depends on your integration
    next_triggered_by: 'customer' // 'merchant' for MIT and 'customer' for CIT
  }).then((response) => {
    // Listen to the request response
    /* Handle response */
    window.alert(JSON.stringify(response));
  });
});

Step 5: Confirm the PaymentIntent

Call confirmPaymentIntent( ) by passing the following fields when the shopper clicks the Submit button after entering payment details.

  • element: The element type - card or cardNumber - depending on your integration

  • intent_id: The id of the PaymentIntent you want to confirm and complete.

  • client_secret: The client_secret of the PaymentIntent you want to confirm and complete.

After the PaymentIntent succeeds, Airwallex automatically attaches the payment details (in a PaymentMethod object) to your Customer.

Customer-initiated subsequent payments

Follow these integration steps to accept customer-initiated subsequent payments.

Step 1: Create a PaymentIntent

Call Create a PaymentIntent API API by providing the amount, currency, and id of the shopper in the customer_id parameter. Save the returned intent id and client_secret.

Step 2: Retrieve saved PaymentConsents

Use the customer_id parameter to retrieve a list of PaymentConsents API associated with your Customer, and display on the checkout page for selection. This allows the shopper to choose their preferred PaymentConsent for the payment.

Step 3: Confirm the PaymentIntent

Call confirmPaymentIntent( ) with the following fields when the shopper selects the saved card.

  • intent_id: The id of the PaymentIntent you want to confirm and complete.

  • client_secret: The client_secret of the PaymentIntent you want to confirm and complete.

  • payment_consent_id: The PaymentConsent id associated with the saved card selected by the shopper.

With CVC input

When creating subsequent customer-initiated payments on a saved card, you may want to recollect the CVC of the card as an additional fraud measure to verify the shopper. To support this, ensure you set requires_cvc to true when you call createPaymentConsent( ). Follow steps 1 to 2 from Customer-initiated subsequent payments together with the steps below to build your integration.

A payment may succeed even with a failed CVC check. To prevent this, configure your Risk management rules to block payments when CVC verification fails.

Step 1: Add CVC element to your checkout page

Create an empty container div with a unique id in your payment form and a Submit button to trigger the payment request. Airwallex inserts an iframe into this div that securely collects CVC information.

<div style="{containerStyle}">
      <div>Cvc</div>
      <div id="cvc"></div>
    </div>
<button id="submit">Submit</button>

When the payment form above has loaded, create the Split Card CVC Element by specifying the Element type as cvc and mount( ) it to the container div in your payment form.

const cvc = Airwallex.createElement('cvc');
cvc.mount('cvc');

Ensure that the payment form only contains one Element with cvc id. The CVC Element should only be mounted once in a single payment flow.

Step 2: Confirm the PaymentIntent

When the shopper clicks the Submit button, call confirmPaymentIntent( ) by passing the following fields to complete the payment:

  • element: The cvc Element

  • id and client_secret of the PaymentIntent

  • payment_consent_id : The PaymentConsent id associated with the saved card selected by the shopper.

// Add a button handler
document.getElementById('submit').addEventListener('click', () => {
  Airwallex.confirmPaymentIntent({
    element: cvc, // Provide the cvc element
    id: 'replace-with-your-intent-id', // Payment Intent ID
    client_secret: 'replace-with-your-client-secret', // Client Secret
    payment_consent_id: 'replace-with-your-consent-id', // PaymentConsent id of the payment consent the customer had selected
  }).then((response) => {
    //  Listen to the request response
    /* Handle response */
    window.alert(JSON.stringify(response));
  });
});

Merchant-initiated subsequent payments

Follow these integration steps to trigger subsequent payments using saved payment details. Note that you must integrate subscription management into your application to initiate scheduled payments at set intervals for an agreed amount.

Step 1: Create a PaymentIntent

Call Create a PaymentIntent API API by providing the amount, currency, and id of the shopper in the customer_id parameter. Save the returned intent id and client_secret.

Step 2: Confirm the PaymentIntent

Call Confirm a PaymentIntent API API with the following parameters to charge the shopper.

  • intent_id: The id of the PaymentIntent you want to confirm and complete.

  • client_secret: The client_secret of the PaymentIntent you want to confirm and complete.

  • customer_id: The id of the Customer associated with the saved payment method.

  • payment_consent_reference.id: The PaymentConsent id associated with the saved payment method.

On this page