Save and reuse payment details

Copy for LLMView as Markdown

Saving and reusing payment details lets returning shoppers pay faster and enables you to run recurring and off-session charges without asking for payment details each time. This is built on top of Credential-on-file (CoF) payments, where the shopper explicitly authorizes you to store their payment credentials for future use.

With Payments API integration, you can choose to store shopper 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 Confirm a PaymentIntent API request, it processes the payment and returns a payment method identifier, which you can use to reference the saved payment information in subsequent payments.

This integration information is specific to card payments. For registered checkout flows related to direct debit and e-wallets, see Local payment method payments.

Before you begin

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 shopper's card details without an upfront payment, allowing you to charge them at a later time. This is beneficial for onboarding shoppers and storing their payment information for future recurring or one-time payments, either initiated by you or by the shopper 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 shopper, 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 shoppers. Set the amount to 0 and save the returned intent id.

Example request

Shell

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

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.

The request payload depends on whether the subsequent payment will be a CIT or a MIT.

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}

Set payment_consent.next_triggered_by to merchant and set payment_consent.merchant_trigger_reason according to the MIT type you are registering.

Set payment_consent.merchant_trigger_reason to scheduled. Used when payments are collected at fixed, recurring intervals.

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": "scheduled"
13    },
14    "payment_method_options": {
15        "card": {
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}

Set payment_consent.merchant_trigger_reason to unscheduled. Used when payments do not follow a fixed schedule, such as one-off charges made without the shopper being in session.

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": "unscheduled"
13    },
14    "payment_method_options": {
15        "card": {
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}

Set payment_consent.merchant_trigger_reason to installments. Used when the total amount is collected from the shopper over multiple installment payments. For this option, you must provide additional installment details under the 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 shopper'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 shopper 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.

Collect a subsequent payment using saved 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).

If the provided payment_method.id is linked to multiple agreements (subscriptions or a CIT), Airwallex will automatically identify the relevant agreement using the value in the triggered_by field. For cards configured with multiple Merchant-Initiated Transactions (MITs), the most recent and active MIT agreement will be used for subsequent payment collections.

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 a CIT or a MIT.

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 shopper 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}

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.

The request shape is the same for scheduled, unscheduled, and installment MIT charges when you use a saved payment_method.id; Airwallex applies the active PaymentConsent. When multiple MIT agreements exist on the same payment method, include payment_consent_id to target the correct agreement (see Payment scenarios).

Use when collecting a charge against a scheduled MIT consent (recurring on a fixed interval).

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}

Use when collecting a charge against an unscheduled MIT consent (off-session charges without a fixed cadence).

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}

Use when collecting an installment under an installments MIT consent. Include payment_consent_id when the payment method has more than one MIT agreement so Airwallex routes the charge to the correct plan.

Example request:

JSON

1{
2    "customer_id": "cus_sgdv77ldrh3orm9rlp2",
3    "payment_method": {
4        "id": "mtd_sgdv8bwxbh3ol8y67nx"
5    },
6    "triggered_by": "merchant",
7    "payment_consent_id": "pct_sgdv8bwxbh3ol8y67nx",
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 shopper has saved with you to set up a new payment agreement with your shopper. Scenarios include:

Shoppers setting up a new MIT payment have the option to use an existing card number or payment method. This can be one already associated with a CIT agreement or another previously established MIT agreement.
When making a one-time payment, shoppers can choose to reuse a card number which is associated with a MIT agreement.

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

As a prerequisite, complete storing payment method details as detailed in previous sections.
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 shopper.
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.
Once a shopper 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.
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}

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.

As a prerequisite, complete storing payment method details as detailed in previous sections.
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 shopper.
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.
Once a shopper 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.
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": "customer"
8    },
9    "payment_method_options": {
10        "card": {
11            "authorization_type": "final_auth",
12            "auto_capture": true
13        }
14    },
15    "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",
16    "return_url": "https://www.airwallex.com/"
17}

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 agreement	Type	Description	API Usage	Notes
N/A	Initial CIT	Your shopper has agreed to save the card on file, allowing them to reuse the saved payment method for subsequent purchases.	Confirm Payment with `payment_consent.next_triggered_by: customer`	`next_triggered_by`: Indicates which party will trigger subsequent payments in the series.
N/A	Initial MIT	Your shopper has agreed to be billed when they are not in session. This can be a recurring subscription or a one-time unscheduled collection.	Confirm Payment with `payment_consent.next_triggered_by: merchant` and `merchant_trigger_reason: scheduled/unscheduled/installments`	`scheduled`: Series of payments collected with similar amounts at fixed intervals. `unscheduled`: Single or multiple payments with varying amounts without a fixed interval. `installments`: Principal amount broken down into fixed amounts for a limited period.

Existing customer

Existing agreement	Type	Description	API Usage	Notes
Initial CIT	Subsequent CIT	Your shopper returns for the next purchase using their saved credentials.	Confirm Payment with `payment_method.id` and `triggered_by: customer`	`triggered_by`: Indicates who triggered the current payment. This field allows you to reuse the saved payment method without referring to the `payment_consent.id`.
Initial MIT	Subsequent MIT	You collect a subscription or unscheduled payment when the shopper is not in session.	Confirm Payment with `payment_method.id` and `triggered_by: merchant`	Airwallex automatically identifies the payment consent with MIT (Merchant-Initiated Transaction) configuration linked to the payment method. The specific MIT type (UNSCHEDULED, SCHEDULED, or INSTALLMENTS) is determined accordingly.
CIT only	New MIT	You set up a new agreement with the shopper that enables you to collect payment when they are not in session. The shopper has already saved their card information with you for CITs.	Confirm Payment with `payment_method.id`, `payment_consent.next_triggered_by: merchant`, and `merchant_trigger_reason: scheduled/unscheduled`	Airwallex automatically identifies the new combination and processes it as an Initial MIT payment. Initial MITs may require additional authentication due to compliance or risk reasons. The `merchant_trigger_reason` field is optional; the default value for MITs is `unscheduled`.
MIT only	New CIT	You process a CIT where your shopper chooses to checkout using their saved card that is used for an ongoing subscription.	Confirm Payment with `payment_method.id` and `triggered_by: customer`
CIT and MIT	New MIT	You set up a second MIT agreement with the shopper. This could be due to the type of product being sold or payment frequency being different.	Confirm Payment with `payment_method.id`, `payment_consent.next_triggered_by: merchant`, and `merchant_trigger_reason: scheduled/unscheduled`	The shopper should be in session when setting up a new recurring or subscription agreement. Initial MITs may require additional authentication due to compliance or risk reasons.
CIT and MIT 1 and MIT 2	Subsequent MIT 1	You collect a subsequent payment for MIT agreement number 1.	Confirm Payment with `payment_consent_id`.	To ensure accurate authorization requests to the issuing bank via the card network, provide the `payment_consent_id` when multiple Merchant-Initiated Transaction (MIT) agreements are configured on the same payment method. If not provided, Airwallex defaults to the last MIT type used, which may lead to inaccuracies.

External recurring data

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

Instead of creating a PaymentConsent in Airwallex, 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. Airwallex uses this metadata to format the authorization according to scheme CoF/recurring rules, so you get correct approvals, liability, and compliance behaviour without migrating or storing cards inside Airwallex.

The payment can be completed with a single Create a PaymentIntent API call, removing the need to perform separate Create and Confirm steps.

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:

The payload depends on whether the subsequent payment will be a CIT or a MIT.

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}

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

Set merchant_trigger_reason in external_recurring_data according to the MIT type you are registering.

Set merchant_trigger_reason to scheduled when payments are collected at fixed, recurring intervals.

Example request

JSON

1{
2  "external_recurring_data": {
3    "initial_payment": "TRUE",
4    "merchant_trigger_reason": "scheduled"
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}

Set merchant_trigger_reason to unscheduled when payments do not follow a fixed schedule, such as one-off charges made without the shopper being in session.

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}

Set merchant_trigger_reason to installments when the total amount is collected over multiple installment payments. Provide installment schedule fields under payment_consent.terms_of_use at the request root when your integration requires them (see Confirm a PaymentIntent API).

Example request

JSON

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

Collect a subsequent payment using saved details

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:

The payload depends on whether the subsequent payment will be a CIT or a MIT.

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}

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.
original_transaction_id: Provide the payment_method_transaction_id returned in the initial payment response.

Set merchant_trigger_reason in external_recurring_data according to the MIT type you are collecting.

Set merchant_trigger_reason to SCHEDULED when collecting a charge on a fixed recurring cadence.

Example request

JSON

1{
2  "external_recurring_data": {
3    "initial_payment": "FALSE",
4    "triggered_by": "merchant",
5    "merchant_trigger_reason": "scheduled",
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}

Set merchant_trigger_reason to unscheduled when collecting an off-session charge without a fixed schedule.

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}

Set merchant_trigger_reason to installments when collecting an installment. Include terms_of_use inside external_recurring_data when required for your plan (see Confirm a PaymentIntent API).

Example request

JSON

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

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:

When both payment_method.id and payment_method object are provided, Airwallex uses the payment_method.id and updates it with allowed fields from the payment_method object, including CVC and billing information.
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.
When both the payment_method object and payment_consent object are provided, Airwallex creates a new PaymentConsent using the payment_method.id or payment_method object. The payment_consent object data is ignored in this case.
When both payment_consent_id and payment_method.id or payment_method object are provided, Airwallex uses the payment_consent_id and ignores the payment_method.id.
When both payment_consent_id and payment_consent object are provided, the payment_consent_id takes precedence, and the payment_consent object is ignored.
When customer_id is not provided in both Create and Confirm PaymentIntent, Airwallex returns a validation_error when you confirm the PaymentIntent.
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.
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 shopper. While the initial payment requires shopper authorization, all subsequent MITs are automatically processed by the merchant using that original authorization. Typical use-cases include:

Subscription businesses (for example, monthly billing, auto-renewal)
Off-session charges (billing after service has occurred)
Variable or recurring payments as per shopper'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 (for example, monthly, yearly), and renewal/cancellation policies prominently on the checkout page before the shopper completes a transaction.
Use a consent checkbox that is separate from other transaction elements, making clear that the shopper 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 sign-up and in account settings, clearly outline the process to end or pause subscriptions, ensuring shoppers 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 sign-up process.
Allow cancellation through all channels by which shoppers could subscribe (for example, 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 shoppers to manage their subscriptions, with continuous protection against Account Takeover (ATO) risks.

To ensure you always have the most up-to-date card details for your shoppers, even if their card is renewed or replaced, Airwallex will automatically enroll your account in our Network tokens and Account Updater features.

Was this page helpful?