Registered user checkout

With native API integration, you can choose to store customer card details directly with Airwallex using gateway tokenization. This approach minimizes your handling of sensitive card data, reducing PCI compliance requirements and security risks. When Airwallex receives the payment details from your Confirm PaymentIntent request, 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 Native API 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 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 API reference API to familiarize yourself with the API endpoints, parameters, and fields.

• 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. 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 returned intent id.

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

Proceed to Confirm PaymentIntent API you have initiated in Step 2. Include the intended usage details of the Payment Consent object—this helps Airwallex understand if the subsequent payment will be initiated by your shopper or yourself. Store the payment_consent_id and the payment_method.id returned in the response.

For customer-initiated subsequent (CIT) payments:

Set payment_consent.next_triggered_by to customer.

Example request:

JSON
1{
2    "customer_id": "cus_sgdv77ldrh3orm9rlp2",
3    "payment_method": {
4      "number": "4035501000000008",
5      "expiry_month": "03",
6      "expiry_year": "2030",
7      "name": "John Doe",
8      "cvc": "737"
9    },
10    "payment_consent": {
11        "next_triggered_by": "customer"
12    },
13    "payment_method_options": {
14        "card": {
15            "authorization_type": "final_auth",
16            "auto_capture": true
17        }
18    },
19    "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
20    "return_url": "https://www.airwallex.com/"
21}

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 request:

JSON
1{
2    "customer_id": "cus_sgdv77ldrh3orm9rlp2",
3    "payment_method": {
4      "number": "4035501000000008",
5      "expiry_month": "03",
6      "expiry_year": "2030",
7      "name": "John Doe",
8      "cvc": "737"
9    },
10    "payment_consent": {
11        "next_triggered_by": "merchant",
12        "merchant_trigger_reason": "installments",
13        "terms_of_use": {
14            "payment_amount_type": "FIXED",
15            "fixed_payment_amount": 100,
16            "payment_schedule": {
17                "period": 1,
18                "period_unit": "MONTH"
19            },
20            "total_billing_cycles": 12,
21            "billing_cycle_charge_day": 1,
22            "start_date": "2025-05-01",
23            "end_date": "2026-05-01"
24        }
25    },
26    "payment_method_options": {
27        "card": {
28            "authorization_type": "final_auth",
29            "auto_capture": true
30        }
31    },
32    "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
33    "return_url": "https://www.airwallex.com/"
34}

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 create and confirm a PaymentIntent using the customer_id and payment_method.id as input. This functionality allows your shoppers to pay for their current purchases using saved card details (cardholder-initiated transactions (CITs)), and enables you, the merchant, to process subscriptions or unscheduled merchant-initiated transactions (MITs).

Step 1: Create a PaymentIntent

Initiate a payment request by calling Create a PaymentIntent API API. This request should include the customer_id generated by Airwallex when you registered your Customer. Save the returned intent id.

Step 2: Confirm the PaymentIntent

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

Customer-initiated payment:

Call Confirm PaymentIntent API API with the payment_method.id generated by Airwallex when you stored the payment method. Set triggered_by to customer. For saved cards, the customer will need to enter their security code (CVC) for verification to complete the payment.

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. For cards, include the cvc field.
• triggered_by: Set to customer.
• payment_method_options: Configuration options for the payment method.

Example request:

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

Merchant-initiated payment:

Call Confirm PaymentIntent API API with the payment_method.id generated by Airwallex when you stored the payment method. Set triggered_by to merchant.

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.

Example request:

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

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:

1. As a prerequisite, complete storing payment method details as detailed in previous sections.

2. Initiate a payment request by calling Create a PaymentIntent API API. This request should include the customer_id generated by Airwallex when you registered your customer.

3. Get a list of all saved payment methods that are linked to the Customer by calling Get list of all Payment Methods API using the customer_id as input.

4. Once a customer selects any existing payment method, proceed to call Confirm PaymentIntent API API with details of new MIT under payment_consent object and payment_method.id as input.

5. Store the payment_consent_id returned to initiate subsequent payments on the payment consent.

Example request:

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

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

1. As a prerequisite, complete storing payment method details as detailed in previous sections.
2. Initiate a payment request by calling Create a PaymentIntent API API. This request should include the customer_id generated by Airwallex when you registered your customer.
3. Get a list of all saved payment methods that are linked to the Customer by calling Get list of all Payment Methods API using the customer_id as input.
4. Once a customer selects any existing payment method, proceed to call Confirm PaymentIntent API API with details of new CIT under payment_consent object and payment_method.id as input.
5. Store the payment_consent_id returned to initiate subsequent payments on the payment consent.

Example request:

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

Payment scenarios

The following table details the API field usage for various use cases, specifically clarifying the distinctions between the next_triggered_by and triggered_by fields.

• next_triggered_by: Use this field to indicate how the card saved on file will be used for subsequent payments. It’s recommended when the PAN is being stored for the first time or when setting up a new usage pattern.
• triggered_by: Use this field to indicate how the stored payment method details are being used for the current payment. It’s recommended when you’re using a payment_method.id instead of the PAN details.

New customer

Existing customer

External recurring data

Airwallex offers you the flexibility to store card details within your system environment. Doing so requires adherence to the PCI DSS Report on Compliance (ROC) standards. For additional details, see PCI DSS requirements .

You can use the external_recurring_data object in Create a PaymentIntent API or Confirm a PaymentIntent API to send the required information to Airwallex to process the payment accurately. Please note that this object is only applicable when the payment_method.type is set to card.

Validate a card or collect an initial payment

Follow these steps to validate a card or collect an initial payment when storing card details externally:

Step 1: Create a PaymentIntent

Create a PaymentIntent by calling Create a PaymentIntent API API. Include the card details in payment_method.card. Set the amount to 0 if you only want to validate the card, or provide a non-zero amount if you want to collect an immediate payment.

Step 2: Define the transaction scenario

Include the external_recurring_data object in your request to define the transaction scenario:

For customer-initiated subsequent (CIT) payments:

• initial_payment: Set this field to TRUE when the shopper is saving their card details for the first time or when establishing a new subscription agreement.

Example request:

JSON
1{
2  "external_recurring_data": {
3    "initial_payment": "TRUE"
4  },
5  "payment_method": {
6    "number": "4035501000000008",
7    "expiry_month": "03",
8    "expiry_year": "2030",
9    "name": "John Doe",
10    "cvc": "737"
11  },
12  "payment_method_options": {
13    "card": {
14      "authorization_type": "final_auth",
15      "auto_capture": true
16    }
17  },
18  "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
19  "return_url": "https://www.airwallex.com/"
20}

For merchant-initiated subsequent (MIT) payments:

• initial_payment: Set this field to TRUE when the shopper is saving their card details for the first time or when establishing a new subscription agreement.
• merchant_trigger_reason: This field is required only when you are setting up MIT payments. Airwallex will use the value UNSCHEDULED by default. Use 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.
• If you are setting up an MIT agreement, store the payment_method_transaction_id returned in the API response. Providing this identifier in all following payment requests is strongly recommended to increase the success rate of subsequent Merchant-Initiated Transaction (MIT) payments.

Example request:

JSON
1{
2  "external_recurring_data": {
3    "initial_payment": "TRUE",
4    "merchant_trigger_reason": "UNSCHEDULED"
5  },
6  "payment_method": {
7    "number": "4035501000000008",
8    "expiry_month": "03",
9    "expiry_year": "2030",
10    "name": "John Doe",
11    "cvc": "737"
12  },
13  "payment_method_options": {
14    "card": {
15      "authorization_type": "final_auth",
16      "auto_capture": true
17    }
18  },
19  "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
20  "return_url": "https://www.airwallex.com/"
21}

Collect subsequent payments

Follow these steps to collect subsequent payments when storing card details externally:

Step 1: Create a PaymentIntent

Create a PaymentIntent by calling Create a PaymentIntent API API. Include the card details in payment_method.card. The amount must be non-zero as this is a subsequent payment.

Step 2: Define the transaction scenario

Include the external_recurring_data object in your request to define the transaction scenario:

For customer-initiated subsequent (CIT) payments:

• initial_payment: Set this field to FALSE. This will be the default value used by Airwallex if not provided.
• triggered_by: Identify the initiator of the payment. Set this to CUSTOMER.

Example request:

JSON
1{
2  "external_recurring_data": {
3    "initial_payment": "FALSE",
4    "triggered_by": "CUSTOMER"
5  },
6  "payment_method": {
7    "number": "4035501000000008",
8    "expiry_month": "03",
9    "expiry_year": "2030",
10    "name": "John Doe",
11    "cvc": "737"
12  },
13  "payment_method_options": {
14    "card": {
15      "authorization_type": "final_auth",
16      "auto_capture": true
17    }
18  },
19  "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
20  "return_url": "https://www.airwallex.com/"
21}

For merchant-initiated subsequent (MIT) payments:

• initial_payment: Set this field to FALSE. This will be the default value used by Airwallex if not provided.
• triggered_by: Identify the initiator of the payment. Set this to MERCHANT.
• merchant_trigger_reason: This field is required only when you are collecting MIT payments and triggered_by field is set to MERCHANT. Use 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.
• original_transaction_id: Provide the payment_method_transaction_id returned in the initial payment response.
• terms_of_use: Fill this block with required fields when the merchant_trigger_reason is INSTALLMENTS.

Example request:

JSON
1{
2  "external_recurring_data": {
3    "initial_payment": "FALSE",
4    "triggered_by": "MERCHANT",
5    "merchant_trigger_reason": "UNSCHEDULED",
6    "original_transaction_id": "485224265480053"
7  },
8  "payment_method": {
9    "number": "4035501000000008",
10    "expiry_month": "03",
11    "expiry_year": "2030",
12    "name": "John Doe",
13    "cvc": "737"
14  },
15  "payment_method_options": {
16    "card": {
17      "authorization_type": "final_auth",
18      "auto_capture": true
19    }
20  },
21  "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
22  "return_url": "https://www.airwallex.com/"
23}

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.

Validation rules

The following rules apply when creating and confirming PaymentIntents with saved payment methods:

1. When both Payment Method ID and Payment Method object are provided: Airwallex uses the Payment Method identifier and updates it with allowed fields from the Payment Method object, including CVC and billing information.

2. When collecting a MIT subsequent payment using an unverified payment method: If the initial transaction was not successful and the payment method is not verified, Airwallex processes the payment as an Initial MIT. Airwallex may trigger 3DS authentication due to compliance or risk reasons.

3. When both Payment Method object and Payment Consent object are provided: Airwallex creates a new Payment Consent using the Payment Method ID or Payment Method object. The Payment Consent object data is ignored in this case.

4. When both Payment Consent ID and Payment Method (ID or object) are provided: Airwallex uses the Payment Consent ID and ignores the Payment Method ID.

5. When both Payment Consent ID and Payment Consent object are provided: The Payment Consent ID takes precedence, and the Payment Consent object is ignored.

6. When Customer ID is not provided in both Create and Confirm PaymentIntent: Airwallex returns a validation_error when you confirm the payment intent.

7. When an incorrect or non-existent identifier is used: If you use an incorrect or non-existent customer_id, payment_method.id, or payment_consent_id in the PaymentIntent request, Airwallex returns a resource_not_found error.

8. When a disabled or unverified payment method is used: If you use a disabled or unverified payment_method.id in the PaymentIntent request, Airwallex returns an invalid_status_for_operation error.

Best practices for handling MITs

Merchant-Initiated Payments (MIT) enable merchants to automatically process payments based on a prior agreement (mandate) with the customer. While the initial payment requires customer authorization, all subsequent MITs are automatically processed by the merchant using that original authorization. Typical use-cases include:

• Subscription businesses (e.g., monthly billing, auto-renewal)
• Off-session charges (billing after service has occurred)
• Variable or recurring payments as per customer's mandate

Merchant-Initiated Transactions (MITs) present increased costs for merchants due to their inherent complexities and risks. These often stem from insufficient disclosure to shoppers regarding subscription terms or delayed charges, which can result in disputes. Additionally, establishing an MIT is subject to stricter controls, such as Strong Customer Authentication (SCA), mandated by regulatory bodies and card scheme rules. To navigate these complexities effectively, we recommend the following best practices for managing your MIT payments:

Clear checkout and subscription terms

• Display subscription costs, frequency (e.g., monthly, yearly), and renewal/cancellation policies prominently on the checkout page before the customer completes a transaction.
• Use a consent checkbox that is separate from other transaction elements, making clear that the customer is authorizing recurring billing, with details on the amount and billing interval.
• Avoid jargon or hidden terms—use plain, readable language and prominent font or color to highlight key information.

Transparent communications and reminders

• Send pre-renewal notifications several days before a subscription is due to renew, explaining the upcoming charge and offering a direct link to manage or cancel the subscription.
• At signup and in account settings, clearly outline the process to end or pause subscriptions, ensuring customers are aware and able to access these controls easily.

Cancellation path and UX

• Give users a direct, unobstructed path to cancellation from their profile or billing management page, with no more friction than the signup process.
• Allow cancellation through all channels by which customers could subscribe (e.g., web, app, phone), not exclusively through customer service or email.

Shopper account security

• Subscription customers require individual password-protected accounts with two-factor authentication (2FA).
• Secure login must be available for customers to manage their subscriptions, with continuous protection against Account Takeover (ATO) risks.