Airwallex logo
Airwallex logo

Registered user checkout

Hosted Payment Page allows you to save payment details for future payments. When Airwallex receives the payment details from the hosted 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 Hosted Payment Page integration:

Before you begin

Before you implement the integration, consider the following:

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 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 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: Confirm the payment method details to be saved

Redirect your shopper to the Hosted Payment Page JS by passing the following fields in the redirectToCheckout() function:

  • intent_id: The PaymentIntent ID from Step 2.
  • client_secret: The client secret from Step 2.
  • currency: The currency code.
  • payment_consent: An object containing the intended usage details of the agreement.

Include the intended usage details of the agreement to register it. This helps Airwallex understand if the subsequent payment will be initiated by your customer 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
1import { init } from '@airwallex/components-sdk';
2

3const { payments } = await init({
4  env: 'demo',
5  enabledElements: ['payments'],
6});
7

8payments.redirectToCheckout({
9  intent_id: 'replace-with-your-intent-id',
10  client_secret: 'replace-with-your-client-secret',
11  currency: 'replace-with-your-currency',
12  payment_consent: {
13    next_triggered_by: 'customer'
14  }
15});

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
1import { init } from '@airwallex/components-sdk';
2

3const { payments } = await init({
4  env: 'demo',
5  enabledElements: ['payments'],
6});
7

8payments.redirectToCheckout({
9  intent_id: 'replace-with-your-intent-id',
10  client_secret: 'replace-with-your-client-secret',
11  currency: 'replace-with-your-currency',
12  payment_consent: {
13    next_triggered_by: 'merchant',
14    merchant_trigger_reason: 'scheduled'
15  }
16});

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:

Call redirectToCheckout() function with the following details. Airwallex will list all the payment methods saved on the customer, allowing your shopper to select any of the saved payment methods. For a saved card, the shopper will be prompted to enter their CVC of the card as an additional fraud measure to verify the shopper.

Required fields:

  • intent_id: The PaymentIntent ID from Step 1.
  • client_secret: The client secret from Step 1.
  • currency: The currency code.

Example:

JavaScript
1import { init } from '@airwallex/components-sdk';
2

3const { payments } = await init({
4  env: 'demo',
5  enabledElements: ['payments'],
6});
7

8payments.redirectToCheckout({
9  intent_id: 'replace-with-your-intent-id',
10  client_secret: 'replace-with-your-client-secret',
11  currency: 'replace-with-your-currency'
12});

Merchant-initiated payment:

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

Required fields:

  • 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.
  • payment_consent_id: (Optional) The id of the PaymentConsent must be provided when the account has mutiple MITs associated with it.

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) payment 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:

  1. Create a PaymentIntent using the customer_id that has been created.

  2. Configure the redirectToCheckout() 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.

  3. Your shopper will now be shown a selection of all the cards that are linked to the customer_id regardless of whether they are stored for CITs or MITs.

  4. 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?