Registered user checkout

This implementation applies to Card Element and Split Card Element integrations.

Embedded Elements integration allows you to save payment details for future payments. When Airwallex receives the payment details from your embedded checkout page after the shopper clicks 'submit', it processes the payment and returns a payment method identifier, which you can use to reference the saved payment information in subsequent payments.

Saved payment method details may be used to trigger different payment scenarios:

Customer-initiated subsequent payments (CIT): This is useful for recurring shoppers who can make payments by selecting the saved payment method. For saved cards, the shopper will need to enter their security code (CVC) for verification to complete the payment. Note: CVC can be skipped when a card is converted to a network token. For more information, see Network tokenization.
Merchant-initiated subsequent payments (MIT): You as a merchant can initiate scheduled (recurring) or unscheduled (one-time) payments without the shopper involved.

Merchant-initiated transactions (MIT payments) inherently carry a higher risk of fraud. This is because merchants trigger these transactions without direct shopper involvement at the time of purchase. For effective management of MITs, refer to our best practices guide.

You can handle the following payment scenarios via Embedded Elements integration:

Save payment details without a payment
Save payment details during payment
Subsequent payment collection using saved payment details
Reuse saved payment details to set up a new payment agreement with your customer

Before you begin

Before you implement the integration, consider the following:

Ensure your Airwallex account has been activated for online payments.
Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
Review the Card Element JS and Split Card Element JS documentation to familiarize yourself with the Embedded Elements methods, parameters, and properties.
Install Airwallex.js JS. If your integration currently uses Airwallex Payment Elements , refer to our upgrade guide for information on migrating to Airwallex.js.
Download the working sample code to reference as you work through the integration guide.

Save payment details without a payment

You have the option to save a customer's card details without an upfront payment, allowing you to charge them at a later time. This is beneficial for onboarding customers and storing their payment information for future recurring or one-time payments, either initiated by you or by the customer themselves.

Step 1: Create a Customer

To set a card up for future payments, you must first create a Customer object to which the payment details will be linked. 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 Customer and also the client_secret. Save the customer id and client_secret for later.

Step 2: Create a zero-amount PaymentIntent

To capture the payment card details from your customer, you need to initiate a PaymentIntent by calling Create a PaymentIntent API API. Include the customer_id returned in Step 1—this allows you to link the payment details to already registered customers. Set the amount to 0 and save the client_secret received in the response.

Example request:

Shell
1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/pa/payment_intents/create' \
3--header 'Authorization: Bearer <your_access_token>' \
4--header 'Content-Type: application/json' \
5--data '{
6  "amount": 0,
7  "currency": "USD",
8  "merchant_order_id": "D202503210001",
9  "customer_id": "cus_sgdv77ldrh3orm9rlp2",
10  "request_id": "b01737e5-c5ab-4765-8834-cbd92dfeaf81",
11  "descriptor": "Airwallex - Test Descriptor",
12  "return_url": "https://www.airwallex.com",
13  "metadata": {
14    "foo": "bar"
15  }
16}'

Step 3: Create your checkout page

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

Step 4: Confirm the payment method details to be saved

When the shopper is ready to proceed with the payment, call confirm() JS by passing the client_secret and PaymentIntent id from Step 2, and the payment_consent object.

Include the intended usage details of the Payment Consent to register it. This helps Airwallex understand if the subsequent payment will be initiated by your shopper or yourself. Query the payment intent or subscribe to payment_intent.succeeded webhook to receive the payment_consent_id, to be used for subsequent payments.

For customer-initiated subsequent (CIT) payments:

Set payment_consent.next_triggered_by to customer.

Example:

JavaScript
1// Add a button handler
2document.getElementById('submit').addEventListener('click', () => {
3  card.confirm({
4    client_secret: 'replace-with-your-client-secret',
5    intent_id: 'replace-with-your-intent-id',
6    payment_consent: {
7      next_triggered_by: 'customer'
8    }
9  }).then((response) => {
10    // Listen to the request response
11    /* Handle response */
12    window.alert(JSON.stringify(response));
13  });
14});

For merchant-initiated subsequent (MIT) payments:

Set payment_consent.next_triggered_by to merchant. In this case, you should also include payment_consent.merchant_trigger_reason with one of the following values:

scheduled: Used when payments are collected at fixed, recurring intervals.
unscheduled: Used when payments do not follow a fixed schedule, such as one-off charges made without the customer being in session.
installments: Used when the total amount is collected from the customer over multiple installment payments. For this option, you must provide additional installment details under payment_consent.terms_of_use object.

Example:

JavaScript
1// Add a button handler
2document.getElementById('submit').addEventListener('click', () => {
3  card.confirm({
4    client_secret: 'replace-with-your-client-secret',
5    intent_id: 'replace-with-your-intent-id',
6    payment_consent: {
7      next_triggered_by: 'merchant',
8      merchant_trigger_reason: 'scheduled'
9    }
10  }).then((response) => {
11    // Listen to the request response
12    /* Handle response */
13    window.alert(JSON.stringify(response));
14  });
15});

Save payment details during payment

You can save a customer's card details during a payment to collect the immediate amount. This allows you to reuse the saved card for future payments, whether initiated by the customer or by you.

Follow the same integration steps as Save payment details without a payment, but in Step 2, when creating the PaymentIntent, provide the pending payment amount instead of setting the amount to 0.

Subsequent payment collection using saved payment details

To collect a subsequent payment using the stored payment details, you need to call Create a PaymentIntent with the customer_id field. The next steps depend on whether the payment is driven by the shopper or by yourself.

Step 1: Create a PaymentIntent

Initiate a payment request by calling Create a PaymentIntent API. Include the customer_id generated by Airwallex when you registered your Customer. Save the returned intent id and client_secret.

Step 2: Confirm the PaymentIntent

The confirmation method depends on whether the payment is customer-initiated or merchant-initiated:

Customer-initiated payment:

To retrieve a list of all payment methods saved under a customer, use Get list of all Payment Methods API and provide the customer_id. Airwallex will return the saved payment methods, which you can then present to your shopper for selection.

When the shopper selects a saved payment method, call confirm() with the following fields:

client_secret: The client secret from Step 1.
intent_id: The PaymentIntent ID from Step 1.
payment_method_id: The PaymentMethod id of the payment method selected by your shopper.
triggered_by: Set to customer.

Example:

JavaScript
1// Add a button handler
2document.getElementById('submit').addEventListener('click', () => {
3  card.confirm({
4    client_secret: 'replace-with-your-client-secret',
5    intent_id: 'replace-with-your-intent-id',
6    payment_method_id: 'replace-with-your-payment_method_id',
7    triggered_by: 'customer'
8  }).then((response) => {
9    // Listen to the request response
10    /* Handle response */
11    window.alert(JSON.stringify(response));
12  });
13});

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.

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.

HTML
1<div>
2  <div>CVC</div>
3  <div id="cvc"></div>
4</div>
5
6<button id="submit">Submit</button>

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

JavaScript
1import { createElement } from '@airwallex/components-sdk';
2
3const cvc = createElement('cvc', {cvcLength: 3}); // specify cvc length based on card brand
4cvc.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 confirm() by passing the following fields to complete the payment:

intent_id: The PaymentIntent ID from Step 1.
client_secret: The client secret from Step 1.
payment_method_id: The PaymentMethod id of the payment method selected by your shopper.
triggered_by: Set to customer.

Example:

JavaScript
1// Add a button handler
2document.getElementById('submit').addEventListener('click', () => {
3  cvc.confirm({
4    intent_id: 'replace-with-your-intent-id',
5    client_secret: 'replace-with-your-client-secret',
6    payment_method_id: 'replace-with-your-payment_method_id',
7    triggered_by: 'customer'
8  }).then((response) => {
9    // Listen to the request response
10    /* Handle response */
11    window.alert(JSON.stringify(response));
12  });
13});

Merchant-initiated payment:

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

Required fields:

intent_id: The id of the PaymentIntent you want to confirm and complete, included as a URL parameter.
customer_id: The id of the Customer associated with the saved payment method.
payment_method: An object containing the id and type of the payment method.
triggered_by: Set to merchant.
payment_method_options: Configuration options for the payment method.

Example request:

JSON
1{
2  "customer_id": "cus_sgdv77ldrh3orm9rlp2",
3  "payment_method": {
4    "id": "mtd_sgdv8bwxbh3ol8y67nx",
5    "type": "card"
6  },
7  "triggered_by": "merchant",
8  "payment_method_options": {
9    "card": {
10      "authorization_type": "final_auth",
11      "auto_capture": true
12    }
13  },
14  "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
15  "return_url": "https://www.airwallex.com/"
16}

Reuse saved payment details to set up a new agreement

You can reuse the payment details your customer has saved with you to set up a new payment agreement with your shopper. Scenarios include:

Customers setting up a new Merchant-Initiated Transaction (MIT) payment have the option to use an existing card number or payment method. This can be one already associated with a Customer-Initiated Transaction (CIT) agreement or another previously established MIT agreement.
When making a one-time payment, customers can choose to reuse a card number which is associated with a MIT agreement.

Set up a new MIT using existing payment details

Follow these steps to set up a new MIT agreement using existing payment details:

Create a PaymentIntent using the customer_id that has been created.
Use the Get list of all Payment Methods API API to list all the saved payment methods on the customer.
Configure the confirm() function with the new intended usage details. You can use the same code sample as detailed in the Save payment details without a payment section for MIT payments.
Airwallex generates a new payment_consent_id after the completion of the payment. Save the payment_consent_id to process subsequent payments.

As this is a new Merchant Initiated Transaction (MIT) setup, shoppers might still need to complete 3DS authentication. This can occur due to fraud risk assessments or PSD2 Strong Customer Authentication (SCA) requirements, and it applies regardless of whether the card is pre-existing.

Make a one-time payment using payment details stored for MIT

You can reuse saved card details for customer-initiated payments with no further integration, as described in the Subsequent payment collection using saved payment details section under the Customer-initiated payment subsection.

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 sandbox environment and then go live in the production environment.

Was this page helpful?