Checkout SessionsEarly access
A Checkout Session manages the setup and lifecycle of an Airwallex-hosted customer checkout experience, including billing subscriptions, one-off payments and payment setup flows. We recommend creating a new Checkout Session each time a customer initiates a purchase. After the customer successfully completes the session, downstream resources such as Billing Customer, Customer, Payment Source, Payment Consent, Subscription, or Invoice may be created depending on the session mode.
POST /api/v1/checkout/checkout_sessions/createGET /api/v1/checkout/checkout_sessions/{id}GET /api/v1/checkout/checkout_sessionsPOST /api/v1/checkout/checkout_sessions/{id}/updatePOST /api/v1/checkout/checkout_sessions/{id}/cancel
Create a Checkout SessionEarly access
POST /api/v1/checkout/checkout_sessions/create
Creates a Checkout Session object.
A Checkout Session is created for one of the following use cases:
- One-off payment. Set
modetoPAYMENT. Omitinvoice_creation, or setinvoice_creation.enabledtofalse. PaymentsDocs. - One-off payment with an invoice. Set
modetoPAYMENTand setinvoice_creation.enabledtotrue. InvoicesDocs. - Subscription payments. Set
modetoSUBSCRIPTION. BillingDocs. - Save a payment method for future use.
- Save as Payment Consent. Set
modetoSETUPand passcustomer_id. This field is required. PaymentsDocs. - Save as Payment Source. Set
modetoSETUPand passbilling_customer_id. This field is required. BillingDocs.
- Save as Payment Consent. Set
The mode of the Checkout Session object, can be one of:
PAYMENT: Accept one-off payments.SUBSCRIPTION: Set up subscriptions.SETUP: Collect payment details to charge your customers later.
Unique request ID specified by the merchant.
ID of the Airwallex payment account to collect payment. You can find this ID in the Airwallex web app > Settings > Account details, within the Account Information section. Required if you have more than 1 payment account in your organisation.
If set, the hosted checkout page displays a back button which allows customers to cancel the flow and be directed to this URL.
The ID of the Billing Customer associated with this Checkout Session.
Use this field when:
modeisPAYMENTandinvoice_creation.enabledistrue.modeisSUBSCRIPTION.modeisSETUPand the collected payment method is saved as a Payment Source. The field is required in this case.
Mutually exclusive with customer_id.
The checkout currency in 3-letter ISO-4217 format. Required when mode is PAYMENT or SETUP.
The prefilled information of the customer. Only applicable when billing_customer_id and customer_id are omitted and mode is not SETUP.
Two-letter ISO 3166 country code of the shopper's country. Strongly recommended — drives which payment methods are surfaced (iDEAL / EPS etc. are country-restricted). Falls back to IP geo when absent.
The prefilled email of the customer.
If this field, or a customer_id or billing_customer_id with an email on file, is provided, the email will be prefilled and will not be editable during checkout.
If no email is provided, the Checkout Session prompts the customer to enter their email.
The prefilled name of the customer.
If this field, or a customer_id or billing_customer_id with a name on file, is provided, the name will be prefilled and will not be editable during checkout.
If no name is provided, the Checkout Session prompts the customer to enter their name.
Type of the customer, one of BUSINESS or INDIVIDUAL. If not provided and no type is available from an existing customer, an "I am purchasing as a business" checkbox is displayed for the customer to self-select.
Provides configuration for the Checkout Session to collect information from customers.
Controls whether the billing address will be collected during checkout.
AUTO: Billing address is collected only when necessary, including when automatic tax is enabled or a tax ID is collected.REQUIRED: Billing address is always collected. Defaults toAUTO.
Controls whether the email address will be collected during checkout.
AUTO: Email address is collected only when necessary, including when an invoice is created or when required by the selected payment method.REQUIRED: Email address is always collected.
AUTOREQUIREDControls whether the name will be collected during checkout.
AUTO: Name is collected only when necessary, including when an invoice is created or when required by the selected payment method.REQUIRED: Name is always collected.
AUTOREQUIREDControls whether the phone number will be collected during checkout.
AUTO: Phone number is collected only when necessary.REQUIRED: Phone number is always collected.
AUTOREQUIREDControls whether the tax ID will be collected for a business customer during checkout.
DISABLED: Tax ID will not be collected.OPTIONAL_IF_SUPPORTED: Tax ID is optionally collected in supported countries by displaying the "I am purchasing as a business" checkbox.REQUIRED_IF_SUPPORTED: Tax ID is always collected when the country is supported. Defaults toOPTIONAL_IF_SUPPORTED.
The ID of the Customer associated with this Checkout Session.
Use this field when:
modeisPAYMENTandinvoice_creation.enabledisfalseor omitted.modeisSETUPand the collected payment method is saved as a Payment Consent. The field is required in this case.
Mutually exclusive with billing_customer_id.
List of discounts to be applied to the subscription or invoice. Discounts of line items are applied before subscription or invoice discounts. Currently, only one element is supported. Only applicable when an invoice is created.
Coupon to redeem into a discount for this resource. Required when type is COUPON.
id of the Coupon object.
Specifies how to obtain the discount. One of: COUPON.
Whether automatic tax is enabled for this checkout. When enabled, the system attempts to calculate taxes for this checkout's invoice automatically. Defaults to false. Only applicable when an invoice is created.
Configuration of the customer experience after the Checkout Session completes. Only applicable when ui_mode is HOSTED.
Whether to display the Airwallex-hosted completion page after the Checkout Session completes and before the customer is redirected to success_url.
Invoice creation settings. Only applicable when mode is PAYMENT.
Whether to create an invoice for this Checkout Session. Only applicable when mode is PAYMENT.
The settings of the invoice to be created when enabled is true.
Number of days from invoice finalization until payment is due.
The tax rate between 0 and 100(%) to be applied to invoices to be generated. The tax will be exclusive. Defaults to 0.
Due date set by the merchant for this invoice, if any. Only one of days_until_due and due_at should be passed.
String used for merchants to share a custom message to their customers. Referenced as memo or invoice note in Webapp.
A set of key-value pairs that you can attach to this object for storing additional information.
ID of the legal entity to be used as billing entity. You can find this ID in the Airwallex web app > Settings. Required when your organisation has more than one legal entity. Only applicable when an invoice is created.
A list of items the customer is purchasing. Required when mode is SUBSCRIPTION or PAYMENT. Not applicable when mode is SETUP.
When mode is SUBSCRIPTION, all line items must have a recurring Price.
When mode is PAYMENT, all line items must have a non-recurring Price.
List of discounts to be applied to the line item. Discounts of line items are applied before subscription or invoice discounts. Currently, only one element is supported. Only applicable when an invoice is created.
Coupon to redeem into a discount for this resource. Required when type is COUPON.
id of the Coupon object.
Specifies how to obtain the discount. One of: COUPON.
One-time price definition following the same schema as the Price resource. Exactly one of price_id or price is required. Only applicable when mode is PAYMENT.
Currency of the price (in 3-letter ISO-4217 format).
Price description. Used for internal classification and identification.
The fixed amount to be charged. Required when pricing_model is FLAT.
Custom key-value pairs attached to the price.
Specify how to calculate the total billing amount when a quantity is provided. One of
FLAT: a fixed price.PER_UNIT: a fixed price per unit quantity. Defaults toPER_UNIT.
One-time product definition following the same schema as the Product. Exactly one of product_id or product is required.
Product name.
Product description. Used for internal classification and identification.
A set of string key-value pairs that you can attach to this object for storing additional information.
The tax category of the product.
Product unit.
ID of the Product object. Exactly one of product_id or product is required.
Whether the price includes tax. Defaults to false.
The amount to be charged per product unit. Required when pricing_model is PER_UNIT.
ID of the Price object. Exactly one of price_id or price is required.
The quantity of the line item being purchased. Defaults to 1.
The effective tax percent of this line item. Only applicable when an invoice is created.
The locale for your website. Defaults to the browser's locale; however, if the browser's locale is not supported, it will default to en.
Accepted values: ar, da, de, en, es, fi, fr, he, id, it, ja, ko, ms, nl, pl, pt, ro, ru, si, sv, tr, vi, ur, zh, zh-HK.
A set of string key-value pairs that you can attach to this object for storing additional information.
A subset of parameters used to create the Payment Intent for this Checkout Session.
Descriptor that will display to the customer on their bank statement. Maximum length is 32. Only applicable when mode is PAYMENT.
The order unique identifier created in merchant's order system that corresponds to this Payment Intent. Maximum length is 64.
Shipping information.
Shipping address.
The two-letter country code in ISO 3166-1 alpha-2 format.
City of the address.
Postcode of the address.
State or province of the address.
Street address.
Shipping fee amount.
First name of the recipient. Maximum of 128 characters.
Last name of the recipient. Maximum of 128 characters.
Phone number of the recipient. Maximum of 50 characters.
Use if customer chose to deliver the item at a later time. The timestamp must include an explicit timezone, for example Z or -04:00.
Shipping method for the product. Maximum of 128 characters.
Payment settings of this Checkout Session.
One or more card networks that you support. Accepted values are visa, mastercard, maestro, unionpay, amex, jcb, diners, and discover. Only applicable when mode is PAYMENT.
Whether the amount should be captured automatically upon successful payment authorization. Set to false to place a hold on the payment method and capture the funds later. Defaults to true. Only applicable when mode is PAYMENT.
Enables the option to "Request an invoice" for payment. After the customer confirms to pay with this option, the status of Checkout Session will transit to COMPLETED, and an invoice will be generated. The invoice will inherit the payment_options of this Checkout Session, and other configurations in invoice_creation.invoice_data. Only applicable when an invoice is created, and the customer type is BUSINESS.
Settings that control whether and how the payment method can be reused for future payments.
Whether and how to store the payment method used in this Checkout Session for future payments. Accepted values:
ENABLED: Always store the payment method when possible; no checkbox is shown.DISABLED: Never store the payment method; always treat the transaction as guest checkout.COLLECT_CONSENT: Show a checkbox and only store the payment method if the customer explicitly opts in. Only applicable to cards.
Indicates who will use the saved Payment Source or Payment Consent to trigger future payments. One of MERCHANT or CUSTOMER.
If MERCHANT, a Payment Source or Payment Consent is created for future use. If CUSTOMER, the payment method is saved only with the payment provider.
Specify which payment methods to display on the Checkout Page and set their display order. Only methods supported for the specified currency and the customer's country code will appear on the Checkout Page. If omitted, all available payment methods are displayed in the default order.
Possible values when mode is SUBSCRIPTION: card, applepay, googlepay, alipaycn, alipayhk, dana, gcash, kakaopay, klarna, rabbit_line_pay, tng, truemoney.
Possible values when mode is PAYMENT: card, applepay, googlepay, wechatpay, alipaycn, alipayhk, gcash, dana, kakaopay, tng, truemoney, bkash, poli, fpx, bank_transfer, alfamart, doku_ewallet, enets, grabpay, indomaret, konbini, online_banking, payeasy, payeasy_atm, seven_eleven, skrill, tesco_lotus, eps, giropay, bancontact, ideal, multibanco, p24, sofort, trustly, dragonpay, blik, mybank, paybybankapp, safetypay, verkkopankki, maxima, narvesen, paypost, perlas_terminals, paysafecash, paysafecard, paysera, satispay, family_mart, hi_life, permata_atm, sam_kiosk, axs_kiosk, esun, shopee_pay, boost, paypal, payu, bitpay, ovo, rabbit_line_pay, ach_direct_debit, bacs_direct_debit, becs_direct_debit, sepa_direct_debit, eft_direct_debit, atome, go_pay, jenius_pay, linkaja, duit_now, pay_now, prompt_pay, airwallex_pay, fps, klarna, korean_local_card, payco, samsung_pay, naver_pay, toss_pay, upi, line_pay, paypay, merpay, d_barai, au_pay, rakuten_pay, zip, spei, afterpay, airi, lumi, payto, twint, venmo, pix, laybuy, cash_app_pay, payme, octopus, tabby, spaylater, wero, jkopay, affirm, bizum, cartes_bancaires, swish, mbway.
Possible values when mode is SETUP: card.
The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method's app or site, with payment status not confirmed. Only applicable when ui_mode is EMBEDDED or ELEMENTS.
The settings of subscription to be passed to the subscription creation upon completion of the Checkout Session in SUBSCRIPTION mode.
Number of days from invoice finalization until payment is due. Defaults to 0.
Invoices for the Subscription will be created using the specified settings.
Memo to be used for the invoices that are generated by this Subscription.
The tax rate between 0 and 100(%) to be applied to invoices to be generated. The tax will be exclusive. Defaults to 0.
The total duration of the subscription.
The number of period units.
Specifies billing duration. One of DAY, WEEK, MONTH or YEAR.
A set of string key-value pairs that you can attach to this object for storing additional information.
Time when the subscription started or scheduled to start. Defaults to start immediately after creation.
The end time of the trial if applicable.
The URL the customer will be directed to after the checkout completion. Only applicable when ui_mode is HOSTED.
The UI mode of the Checkout Session:
HOSTED: Customers complete checkout on an Airwallex-hosted page.EMBEDDED: Embed the checkout UI directly in your website or app.ELEMENTS: Build a custom checkout UI using Airwallex Elements.
Defaults to HOSTED. When no invoice is created, only HOSTED is supported.
Customization options for the Checkout Page.
The layout of the Checkout Page.
Specify the layout for the payment elements. Accepted values are tab and accordion. By default, accordion layout is used on desktop and tab layout is used on mobile. Only applicable when no invoice is created.
Describes the type of transaction being performed in order to customize the submit button text. Accepted values are pay, book, subscribe, and save.
ID of the theme to apply to this Checkout Session, overriding the theme applied to its legal entity. You can find this ID in the Airwallex web app > Settings > Themes.
ID of the Airwallex payment account used to collect payment. You can find this ID in the Airwallex web app > Settings > Account details, within the Account Information section.
The automatic tax status of this checkout. One of:
APPLIED: The automatic tax is applied.DISABLED: The automatic tax is disabled.LOCATION_NOT_SUPPORTED: Automatic tax calculation isn't supported in the customer's location.LOCATION_NOT_REGISTERED_BY_MERCHANT: The merchant isn't registered to collect tax in the customer's location.ADDRESS_INCOMPLETE: The customer address was insufficient or invalid to determine the correct tax.
APPLIEDDISABLEDLOCATION_NOT_SUPPORTEDLOCATION_NOT_REGISTERED_BY_MERCHANTADDRESS_INCOMPLETEIf set, the hosted checkout page displays a back button which allows customers to cancel the flow and be directed to this URL.
ID of the Billing Customer associated with this Checkout Session, if applicable.
Time when the Checkout Session was cancelled.
The client secret used to initialize the Checkout Session in EMBEDDED or ELEMENTS ui_mode. Only present when ui_mode is EMBEDDED or ELEMENTS.
Time when the Checkout Session was completed.
Time when the Checkout Session was created.
The checkout currency in 3-letter ISO-4217 format.
The prefilled information of the customer.
Two-letter ISO 3166 country code of the shopper's country. Strongly recommended — drives which payment methods are surfaced (iDEAL / EPS etc. are country-restricted). Falls back to IP geo when absent.
The prefilled email of the customer.
If this field, or a customer_id or billing_customer_id with an email on file, is provided, the email will be prefilled and will not be editable during checkout.
If no email is provided, the Checkout Session prompts the customer to enter their email.
The prefilled name of the customer.
If this field, or a customer_id or billing_customer_id with a name on file, is provided, the name will be prefilled and will not be editable during checkout.
If no name is provided, the Checkout Session prompts the customer to enter their name.
Type of the customer, one of BUSINESS or INDIVIDUAL. If not provided and no type is available from an existing customer, an "I am purchasing as a business" checkbox is displayed for the customer to self-select.
Provides configuration for the Checkout Session to collect information from customers.
Controls whether the billing address will be collected during checkout.
AUTO: Billing address is collected only when necessary, including when automatic tax is enabled or a tax ID is collected.REQUIRED: Billing address is always collected. Defaults toAUTO.
Controls whether the email address will be collected during checkout.
AUTO: Email address is collected only when necessary, including when an invoice is created or when required by the selected payment method.REQUIRED: Email address is always collected.
AUTOREQUIREDControls whether the name will be collected during checkout.
AUTO: Name is collected only when necessary, including when an invoice is created or when required by the selected payment method.REQUIRED: Name is always collected.
AUTOREQUIREDControls whether the phone number will be collected during checkout.
AUTO: Phone number is collected only when necessary.REQUIRED: Phone number is always collected.
AUTOREQUIREDControls whether the tax ID will be collected for a business customer during checkout.
DISABLED: Tax ID will not be collected.OPTIONAL_IF_SUPPORTED: Tax ID is optionally collected in supported countries by displaying the "I am purchasing as a business" checkbox.REQUIRED_IF_SUPPORTED: Tax ID is always collected when the country is supported. Defaults toOPTIONAL_IF_SUPPORTED.
ID of the Customer from the Payments API associated with this Checkout Session, if applicable.
List of discounts applied to the subscription or invoice. Discounts of line items are applied before subscription or invoice discounts. Currently, only one element is supported.
Specifies how to obtain the discount. One of: COUPON.
Coupon to redeem into a discount for this resource. Only required when type = COUPON.
id of the Coupon object.
Whether automatic tax is enabled for this checkout. When enabled, the system attempts to calculate taxes for this checkout's invoice automatically.
Time when the Checkout Session expires.
Configuration of the customer experience after the Checkout Session completes. Only applicable when ui_mode is HOSTED.
Whether to display the Airwallex-hosted completion page after the Checkout Session completes and before the customer is redirected to success_url.
ID of the Checkout Session object.
Invoice creation settings for this Checkout Session.
Whether an invoice is created for this Checkout Session.
The invoice settings used for this Checkout Session.
Number of days from invoice finalization until payment is due.
The tax rate between 0 and 100(%) to be applied to invoices to be generated. The tax will be exclusive. Defaults to 0.
Due date set by the merchant for this invoice, if any.
String used for merchants to share a custom message to their customers. Referenced as memo or invoice note in Webapp.
A set of key-value pairs that you can attach to this object for storing additional information.
ID of the invoice for the Checkout Session when mode is PAYMENT. Only applicable when status is COMPLETED.
ID of the legal entity to be used as billing entity, which can be retrieved from the legal_entity_id field in the Retrieve account details API response.
A list of items the customer is purchasing.
List of discounts applied to the line item. Discounts of line items are applied before subscription or invoice discounts. Currently, only one element is supported.
Specifies how to obtain the discount. One of: COUPON.
Coupon to redeem into a discount for this resource. Only required when type = COUPON.
id of the Coupon object.
ID of the Price object.
The quantity of the line item being purchased.
The effective tax percent of this line item.
The locale for the Checkout Session.
A set of string key-value pairs that you can attach to this object for storing additional information.
The mode of the Checkout Session object, can be one of:
PAYMENT: Accept one-off payments.SUBSCRIPTION: Set up subscriptions.SETUP: Collect payment details to charge your customers later.
ID of the Payment Consent created when the Checkout Session is completed.
The Payment Intent parameters configured for this Checkout Session.
Descriptor that will display to the customer on their bank statement. Maximum length is 32. Only applicable when mode is PAYMENT.
The order unique identifier created in merchant's order system that corresponds to this Payment Intent. Maximum length is 64.
Shipping information.
Shipping address.
The two-letter country code in ISO 3166-1 alpha-2 format.
City of the address.
Postcode of the address.
State or province of the address.
Street address.
Shipping fee amount.
First name of the recipient. Maximum of 128 characters.
Last name of the recipient. Maximum of 128 characters.
Phone number of the recipient. Maximum of 50 characters.
Use if customer chose to deliver the item at a later time. The timestamp must include an explicit timezone, for example Z or -04:00.
Shipping method for the product. Maximum of 128 characters.
ID of the Payment Intent associated with this Checkout Session.
Payment settings of this Checkout Session.
One or more card networks that you support. Accepted values are visa, mastercard, maestro, unionpay, amex, jcb, diners, and discover. Only applicable when mode is PAYMENT.
Whether the amount should be captured automatically upon successful payment authorization. Set to false to place a hold on the payment method and capture the funds later. Defaults to true. Only applicable when mode is PAYMENT.
Enables the option to "Request an invoice" for payment. After the customer confirms to pay with this option, the status of Checkout Session will transit to COMPLETED, and an invoice will be generated. The invoice will inherit the payment_options of this Checkout Session, and other configurations in invoice_creation.invoice_data. Only applicable when an invoice is created, and the customer type is BUSINESS.
Settings that control whether and how the payment method can be reused for future payments.
Whether and how to store the payment method used in this Checkout Session for future payments. Accepted values:
ENABLED: Always store the payment method when possible; no checkbox is shown.DISABLED: Never store the payment method; always treat the transaction as guest checkout.COLLECT_CONSENT: Show a checkbox and only store the payment method if the customer explicitly opts in. Only applicable to cards.
Indicates who will use the saved Payment Source or Payment Consent to trigger future payments. One of MERCHANT or CUSTOMER.
If MERCHANT, a Payment Source or Payment Consent is created for future use. If CUSTOMER, the payment method is saved only with the payment provider.
Specify which payment methods to display on the Checkout Page and set their display order. Only methods supported for the specified currency and the customer's country code will appear on the Checkout Page. If omitted, all available payment methods are displayed in the default order.
Possible values when mode is SUBSCRIPTION: card, applepay, googlepay, alipaycn, alipayhk, dana, gcash, kakaopay, klarna, rabbit_line_pay, tng, truemoney.
Possible values when mode is PAYMENT: card, applepay, googlepay, wechatpay, alipaycn, alipayhk, gcash, dana, kakaopay, tng, truemoney, bkash, poli, fpx, bank_transfer, alfamart, doku_ewallet, enets, grabpay, indomaret, konbini, online_banking, payeasy, payeasy_atm, seven_eleven, skrill, tesco_lotus, eps, giropay, bancontact, ideal, multibanco, p24, sofort, trustly, dragonpay, blik, mybank, paybybankapp, safetypay, verkkopankki, maxima, narvesen, paypost, perlas_terminals, paysafecash, paysafecard, paysera, satispay, family_mart, hi_life, permata_atm, sam_kiosk, axs_kiosk, esun, shopee_pay, boost, paypal, payu, bitpay, ovo, rabbit_line_pay, ach_direct_debit, bacs_direct_debit, becs_direct_debit, sepa_direct_debit, eft_direct_debit, atome, go_pay, jenius_pay, linkaja, duit_now, pay_now, prompt_pay, airwallex_pay, fps, klarna, korean_local_card, payco, samsung_pay, naver_pay, toss_pay, upi, line_pay, paypay, merpay, d_barai, au_pay, rakuten_pay, zip, spei, afterpay, airi, lumi, payto, twint, venmo, pix, laybuy, cash_app_pay, payme, octopus, tabby, spaylater, wero, jkopay, affirm, bizum, cartes_bancaires, swish, mbway.
Possible values when mode is SETUP: card.
ID of the Payment Source created when the Checkout Session is completed.
The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method's app or site, with payment status not confirmed.
The status of the Checkout Session object, can be one of:
ACTIVE: The Checkout Session is available for the customer to complete a purchase.COMPLETED: The Checkout Session has been completed.CANCELLED: The Checkout Session has been cancelled.EXPIRED: The Checkout Session has expired.
The status automatically changes from ACTIVE to EXPIRED after 1 hour if purchase has not been completed.
The settings of subscription to be passed to the subscription creation upon completion of the Checkout Session in SUBSCRIPTION mode.
Number of days from invoice finalization until payment is due. Defaults to 0.
The billing cycle for recurring charges.
The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
Invoices for the Subscription will be created using the specified settings.
Memo to be used for the invoices that are generated by this Subscription.
The tax rate between 0 and 100(%) to be applied to invoices to be generated. The tax will be exclusive. Defaults to 0.
The total duration of the subscription.
The number of period units.
Specifies billing duration. One of DAY, WEEK, MONTH or YEAR.
A set of string key-value pairs that you can attach to this object for storing additional information.
Time when the subscription started or scheduled to start. Defaults to start immediately after creation.
The end time of the trial if applicable.
ID of the subscription for the Checkout Session when mode is SUBSCRIPTION. Only applicable when status is COMPLETED.
The URL the customer will be directed to after the checkout completion.
The UI mode of the Checkout Session, can be one of:
HOSTED: Customers complete the checkout on an Airwallex-hosted page.
EMBEDDED: Embed the checkout UI directly in your website or app.
ELEMENTS: Build a custom checkout UI using Airwallex Elements.
Customization options for the Checkout Page.
The layout of the Checkout Page.
Specify the layout for the payment elements. Accepted values are tab and accordion. By default, accordion layout is used on desktop and tab layout is used on mobile. Only applicable when no invoice is created.
Describes the type of transaction being performed in order to customize the submit button text. Accepted values are pay, book, subscribe, and save.
ID of the theme to apply to this Checkout Session, overriding the theme applied to its legal entity. You can find this ID in the Airwallex web app > Settings > Themes.
Time when the Checkout Session was last updated.
The URL to the Checkout Session. Only present when status is ACTIVE.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/checkout/checkout_sessions/create' \> --header 'Authorization: Bearer <token>' \> --header 'Content-Type: application/json' \> --data '{> "mode": "PAYMENT",> "request_id": "ee939540-3203-4a2c-9172-89a566485dd9",> "success_url": "https://www.airwallex.com/success",> "account_id": "acct_ncI2nypPKSq2VXKxscAcg",> "back_url": "https://www.airwallex.com/back",> "currency": "USD",> "customer_data_collection": {> "tax_id": "OPTIONAL_IF_SUPPORTED",> "billing_address": "REQUIRED",> "phone_number": "REQUIRED",> "name": "REQUIRED",> "email": "REQUIRED"> },> "customer_id": "cus_hkpd7fedfgb004apkvs",> "invoice_creation": {> "enabled": false> },> "payment_intent_data": {> "descriptor": "AIRWALLEX",> "merchant_order_id": "order_123",> "shipping": {> "address": {> "country_code": "AU",> "city": "Melbourne",> "postcode": "3000",> "state": "VIC",> "street": "1 Collins Street"> },> "fee_amount": 5,> "first_name": "John",> "last_name": "Doe",> "phone_number": "+61400000000",> "shipping_method": "standard"> }> },> "line_items": [> {> "price_id": "pri_hkpd7fedfgb004apkvs",> "quantity": 1> }> ],> "metadata": {> "foo": "bar"> },> "payment_options": {> "payment_method_types": [> "card",> "googlepay",> "applepay"> ],> "auto_capture": true,> "authorization_type": "final_auth",> "allowed_card_networks": [> "visa",> "mastercard"> ],> "payment_method_save": {> "mode": "ENABLED",> "next_triggered_by": "MERCHANT"> }> },> "ui_mode": "HOSTED",> "locale": "en">}'
1{2 "automatic_tax_status": "DISABLED",3 "created_at": "2025-05-10T16:00:30+0000",4 "discounts": [],5 "enable_automatic_tax": false,6 "expires_at": "2025-05-10T17:00:30+0000",7 "id": "bco_sgstcdcpnh8sv3awiwo",8 "mode": "PAYMENT",9 "status": "ACTIVE",10 "success_url": "https://www.airwallex.com/success",11 "updated_at": "2025-05-10T16:00:30+0000",12 "account_id": "acct_ncI2nypPKSq2VXKxscAcg",13 "back_url": "https://www.airwallex.com/back",14 "currency": "USD",15 "customer_data_collection": {16 "tax_id": "OPTIONAL_IF_SUPPORTED",17 "billing_address": "REQUIRED",18 "phone_number": "REQUIRED",19 "name": "REQUIRED",20 "email": "REQUIRED"21 },22 "customer_id": "cus_hkpd7fedfgb004apkvs",23 "invoice_creation": {24 "enabled": false25 },26 "payment_intent_data": {27 "descriptor": "AIRWALLEX",28 "merchant_order_id": "order_123",29 "shipping": {30 "address": {31 "country_code": "AU",32 "city": "Melbourne",33 "postcode": "3000",34 "state": "VIC",35 "street": "1 Collins Street"36 },37 "fee_amount": 5,38 "first_name": "John",39 "last_name": "Doe",40 "phone_number": "+61400000000",41 "shipping_method": "standard"42 }43 },44 "line_items": [45 {46 "price_id": "pri_hkpd7fedfgb004apkvs",47 "discounts": [],48 "quantity": 149 }50 ],51 "metadata": {52 "foo": "bar"53 },54 "payment_options": {55 "payment_method_types": [56 "card",57 "googlepay",58 "applepay"59 ],60 "auto_capture": true,61 "authorization_type": "final_auth",62 "allowed_card_networks": [63 "visa",64 "mastercard"65 ],66 "payment_method_save": {67 "mode": "ENABLED",68 "next_triggered_by": "MERCHANT"69 }70 },71 "ui_mode": "HOSTED",72 "locale": "en",73 "url": "https://checkout.airwallex.com/pay?s=jwt_token"74}
Retrieve a Checkout SessionEarly access
GET /api/v1/checkout/checkout_sessions/{id}
Retrieves a Checkout Session.
ID of the Checkout Session object.
ID of the Airwallex payment account used to collect payment. You can find this ID in the Airwallex web app > Settings > Account details, within the Account Information section.
The automatic tax status of this checkout. One of:
APPLIED: The automatic tax is applied.DISABLED: The automatic tax is disabled.LOCATION_NOT_SUPPORTED: Automatic tax calculation isn't supported in the customer's location.LOCATION_NOT_REGISTERED_BY_MERCHANT: The merchant isn't registered to collect tax in the customer's location.ADDRESS_INCOMPLETE: The customer address was insufficient or invalid to determine the correct tax.
APPLIEDDISABLEDLOCATION_NOT_SUPPORTEDLOCATION_NOT_REGISTERED_BY_MERCHANTADDRESS_INCOMPLETEIf set, the hosted checkout page displays a back button which allows customers to cancel the flow and be directed to this URL.
ID of the Billing Customer associated with this Checkout Session, if applicable.
Time when the Checkout Session was cancelled.
The client secret used to initialize the Checkout Session in EMBEDDED or ELEMENTS ui_mode. Only present when ui_mode is EMBEDDED or ELEMENTS.
Time when the Checkout Session was completed.
Time when the Checkout Session was created.
The checkout currency in 3-letter ISO-4217 format.
The prefilled information of the customer.
Two-letter ISO 3166 country code of the shopper's country. Strongly recommended — drives which payment methods are surfaced (iDEAL / EPS etc. are country-restricted). Falls back to IP geo when absent.
The prefilled email of the customer.
If this field, or a customer_id or billing_customer_id with an email on file, is provided, the email will be prefilled and will not be editable during checkout.
If no email is provided, the Checkout Session prompts the customer to enter their email.
The prefilled name of the customer.
If this field, or a customer_id or billing_customer_id with a name on file, is provided, the name will be prefilled and will not be editable during checkout.
If no name is provided, the Checkout Session prompts the customer to enter their name.
Type of the customer, one of BUSINESS or INDIVIDUAL. If not provided and no type is available from an existing customer, an "I am purchasing as a business" checkbox is displayed for the customer to self-select.
Provides configuration for the Checkout Session to collect information from customers.
Controls whether the billing address will be collected during checkout.
AUTO: Billing address is collected only when necessary, including when automatic tax is enabled or a tax ID is collected.REQUIRED: Billing address is always collected. Defaults toAUTO.
Controls whether the email address will be collected during checkout.
AUTO: Email address is collected only when necessary, including when an invoice is created or when required by the selected payment method.REQUIRED: Email address is always collected.
AUTOREQUIREDControls whether the name will be collected during checkout.
AUTO: Name is collected only when necessary, including when an invoice is created or when required by the selected payment method.REQUIRED: Name is always collected.
AUTOREQUIREDControls whether the phone number will be collected during checkout.
AUTO: Phone number is collected only when necessary.REQUIRED: Phone number is always collected.
AUTOREQUIREDControls whether the tax ID will be collected for a business customer during checkout.
DISABLED: Tax ID will not be collected.OPTIONAL_IF_SUPPORTED: Tax ID is optionally collected in supported countries by displaying the "I am purchasing as a business" checkbox.REQUIRED_IF_SUPPORTED: Tax ID is always collected when the country is supported. Defaults toOPTIONAL_IF_SUPPORTED.
ID of the Customer from the Payments API associated with this Checkout Session, if applicable.
List of discounts applied to the subscription or invoice. Discounts of line items are applied before subscription or invoice discounts. Currently, only one element is supported.
Specifies how to obtain the discount. One of: COUPON.
Coupon to redeem into a discount for this resource. Only required when type = COUPON.
id of the Coupon object.
Whether automatic tax is enabled for this checkout. When enabled, the system attempts to calculate taxes for this checkout's invoice automatically.
Time when the Checkout Session expires.
Configuration of the customer experience after the Checkout Session completes. Only applicable when ui_mode is HOSTED.
Whether to display the Airwallex-hosted completion page after the Checkout Session completes and before the customer is redirected to success_url.
ID of the Checkout Session object.
Invoice creation settings for this Checkout Session.
Whether an invoice is created for this Checkout Session.
The invoice settings used for this Checkout Session.
Number of days from invoice finalization until payment is due.
The tax rate between 0 and 100(%) to be applied to invoices to be generated. The tax will be exclusive. Defaults to 0.
Due date set by the merchant for this invoice, if any.
String used for merchants to share a custom message to their customers. Referenced as memo or invoice note in Webapp.
A set of key-value pairs that you can attach to this object for storing additional information.
ID of the invoice for the Checkout Session when mode is PAYMENT. Only applicable when status is COMPLETED.
ID of the legal entity to be used as billing entity, which can be retrieved from the legal_entity_id field in the Retrieve account details API response.
A list of items the customer is purchasing.
List of discounts applied to the line item. Discounts of line items are applied before subscription or invoice discounts. Currently, only one element is supported.
Specifies how to obtain the discount. One of: COUPON.
Coupon to redeem into a discount for this resource. Only required when type = COUPON.
id of the Coupon object.
ID of the Price object.
The quantity of the line item being purchased.
The effective tax percent of this line item.
The locale for the Checkout Session.
A set of string key-value pairs that you can attach to this object for storing additional information.
The mode of the Checkout Session object, can be one of:
PAYMENT: Accept one-off payments.SUBSCRIPTION: Set up subscriptions.SETUP: Collect payment details to charge your customers later.
ID of the Payment Consent created when the Checkout Session is completed.
The Payment Intent parameters configured for this Checkout Session.
Descriptor that will display to the customer on their bank statement. Maximum length is 32. Only applicable when mode is PAYMENT.
The order unique identifier created in merchant's order system that corresponds to this Payment Intent. Maximum length is 64.
Shipping information.
Shipping address.
The two-letter country code in ISO 3166-1 alpha-2 format.
City of the address.
Postcode of the address.
State or province of the address.
Street address.
Shipping fee amount.
First name of the recipient. Maximum of 128 characters.
Last name of the recipient. Maximum of 128 characters.
Phone number of the recipient. Maximum of 50 characters.
Use if customer chose to deliver the item at a later time. The timestamp must include an explicit timezone, for example Z or -04:00.
Shipping method for the product. Maximum of 128 characters.
ID of the Payment Intent associated with this Checkout Session.
Payment settings of this Checkout Session.
One or more card networks that you support. Accepted values are visa, mastercard, maestro, unionpay, amex, jcb, diners, and discover. Only applicable when mode is PAYMENT.
Whether the amount should be captured automatically upon successful payment authorization. Set to false to place a hold on the payment method and capture the funds later. Defaults to true. Only applicable when mode is PAYMENT.
Enables the option to "Request an invoice" for payment. After the customer confirms to pay with this option, the status of Checkout Session will transit to COMPLETED, and an invoice will be generated. The invoice will inherit the payment_options of this Checkout Session, and other configurations in invoice_creation.invoice_data. Only applicable when an invoice is created, and the customer type is BUSINESS.
Settings that control whether and how the payment method can be reused for future payments.
Whether and how to store the payment method used in this Checkout Session for future payments. Accepted values:
ENABLED: Always store the payment method when possible; no checkbox is shown.DISABLED: Never store the payment method; always treat the transaction as guest checkout.COLLECT_CONSENT: Show a checkbox and only store the payment method if the customer explicitly opts in. Only applicable to cards.
Indicates who will use the saved Payment Source or Payment Consent to trigger future payments. One of MERCHANT or CUSTOMER.
If MERCHANT, a Payment Source or Payment Consent is created for future use. If CUSTOMER, the payment method is saved only with the payment provider.
Specify which payment methods to display on the Checkout Page and set their display order. Only methods supported for the specified currency and the customer's country code will appear on the Checkout Page. If omitted, all available payment methods are displayed in the default order.
Possible values when mode is SUBSCRIPTION: card, applepay, googlepay, alipaycn, alipayhk, dana, gcash, kakaopay, klarna, rabbit_line_pay, tng, truemoney.
Possible values when mode is PAYMENT: card, applepay, googlepay, wechatpay, alipaycn, alipayhk, gcash, dana, kakaopay, tng, truemoney, bkash, poli, fpx, bank_transfer, alfamart, doku_ewallet, enets, grabpay, indomaret, konbini, online_banking, payeasy, payeasy_atm, seven_eleven, skrill, tesco_lotus, eps, giropay, bancontact, ideal, multibanco, p24, sofort, trustly, dragonpay, blik, mybank, paybybankapp, safetypay, verkkopankki, maxima, narvesen, paypost, perlas_terminals, paysafecash, paysafecard, paysera, satispay, family_mart, hi_life, permata_atm, sam_kiosk, axs_kiosk, esun, shopee_pay, boost, paypal, payu, bitpay, ovo, rabbit_line_pay, ach_direct_debit, bacs_direct_debit, becs_direct_debit, sepa_direct_debit, eft_direct_debit, atome, go_pay, jenius_pay, linkaja, duit_now, pay_now, prompt_pay, airwallex_pay, fps, klarna, korean_local_card, payco, samsung_pay, naver_pay, toss_pay, upi, line_pay, paypay, merpay, d_barai, au_pay, rakuten_pay, zip, spei, afterpay, airi, lumi, payto, twint, venmo, pix, laybuy, cash_app_pay, payme, octopus, tabby, spaylater, wero, jkopay, affirm, bizum, cartes_bancaires, swish, mbway.
Possible values when mode is SETUP: card.
ID of the Payment Source created when the Checkout Session is completed.
The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method's app or site, with payment status not confirmed.
The status of the Checkout Session object, can be one of:
ACTIVE: The Checkout Session is available for the customer to complete a purchase.COMPLETED: The Checkout Session has been completed.CANCELLED: The Checkout Session has been cancelled.EXPIRED: The Checkout Session has expired.
The status automatically changes from ACTIVE to EXPIRED after 1 hour if purchase has not been completed.
The settings of subscription to be passed to the subscription creation upon completion of the Checkout Session in SUBSCRIPTION mode.
Number of days from invoice finalization until payment is due. Defaults to 0.
The billing cycle for recurring charges.
The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
Invoices for the Subscription will be created using the specified settings.
Memo to be used for the invoices that are generated by this Subscription.
The tax rate between 0 and 100(%) to be applied to invoices to be generated. The tax will be exclusive. Defaults to 0.
The total duration of the subscription.
The number of period units.
Specifies billing duration. One of DAY, WEEK, MONTH or YEAR.
A set of string key-value pairs that you can attach to this object for storing additional information.
Time when the subscription started or scheduled to start. Defaults to start immediately after creation.
The end time of the trial if applicable.
ID of the subscription for the Checkout Session when mode is SUBSCRIPTION. Only applicable when status is COMPLETED.
The URL the customer will be directed to after the checkout completion.
The UI mode of the Checkout Session, can be one of:
HOSTED: Customers complete the checkout on an Airwallex-hosted page.
EMBEDDED: Embed the checkout UI directly in your website or app.
ELEMENTS: Build a custom checkout UI using Airwallex Elements.
Customization options for the Checkout Page.
The layout of the Checkout Page.
Specify the layout for the payment elements. Accepted values are tab and accordion. By default, accordion layout is used on desktop and tab layout is used on mobile. Only applicable when no invoice is created.
Describes the type of transaction being performed in order to customize the submit button text. Accepted values are pay, book, subscribe, and save.
ID of the theme to apply to this Checkout Session, overriding the theme applied to its legal entity. You can find this ID in the Airwallex web app > Settings > Themes.
Time when the Checkout Session was last updated.
The URL to the Checkout Session. Only present when status is ACTIVE.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request GET \> --url 'https://api.sandbox.airwallex.com/api/v1/checkout/checkout_sessions/checkout_session_id' \> --header 'Authorization: Bearer <token>' \> --header 'Content-Type: application/json'
1{2 "automatic_tax_status": "DISABLED",3 "created_at": "2025-05-10T16:00:30+0000",4 "discounts": [],5 "enable_automatic_tax": false,6 "expires_at": "2025-05-10T17:00:30+0000",7 "id": "bco_sgstcdcpnh8sv3awiwo",8 "mode": "PAYMENT",9 "status": "ACTIVE",10 "success_url": "https://www.airwallex.com/success",11 "ui_mode": "HOSTED",12 "updated_at": "2025-05-10T16:00:30+0000",13 "account_id": "acct_ncI2nypPKSq2VXKxscAcg",14 "back_url": "https://www.airwallex.com/back",15 "currency": "USD",16 "customer_data_collection": {17 "tax_id": "OPTIONAL_IF_SUPPORTED",18 "billing_address": "REQUIRED",19 "phone_number": "REQUIRED",20 "name": "REQUIRED",21 "email": "REQUIRED"22 },23 "customer_id": "cus_hkpd7fedfgb004apkvs",24 "payment_intent_data": {25 "merchant_order_id": "order_123"26 },27 "line_items": [28 {29 "price_id": "pri_hkpd7fedfgb004apkvs",30 "discounts": [],31 "quantity": 132 }33 ],34 "metadata": {35 "foo": "bar"36 },37 "payment_options": {38 "payment_method_types": [39 "card",40 "googlepay",41 "applepay"42 ]43 },44 "url": "https://checkout.airwallex.com/pay?s=jwt_token"45}
Get list of Checkout SessionsEarly access
GET /api/v1/checkout/checkout_sessions
Retrieves a list of Checkout Sessions based on the query parameters.
The start date of created_at in ISO8601 format (inclusive).
A bookmark for use in pagination to retrieve either the next page or the previous page of results. You can fetch the value for this identifier from the response of the previous API call. To retrieve the next page of results, pass the value of page_after (if not null) from the response to a subsequent call. To retrieve the previous page of results, pass the value of page_before (if not null) from the response to a subsequent call.
Number of Checkout Sessions per page. Defaults to 20.
Status of the Checkout Session.
ID of the subscription for the Checkout Session upon completion.
The end date of created_at in ISO8601 format (exclusive).
Paged results.
ID of the Airwallex payment account used to collect payment. You can find this ID in the Airwallex web app > Settings > Account details, within the Account Information section.
The automatic tax status of this checkout. One of:
APPLIED: The automatic tax is applied.DISABLED: The automatic tax is disabled.LOCATION_NOT_SUPPORTED: Automatic tax calculation isn't supported in the customer's location.LOCATION_NOT_REGISTERED_BY_MERCHANT: The merchant isn't registered to collect tax in the customer's location.ADDRESS_INCOMPLETE: The customer address was insufficient or invalid to determine the correct tax.
APPLIEDDISABLEDLOCATION_NOT_SUPPORTEDLOCATION_NOT_REGISTERED_BY_MERCHANTADDRESS_INCOMPLETETime when the Checkout Session was created.
List of discounts applied to the subscription or invoice. Discounts of line items are applied before subscription or invoice discounts. Currently, only one element is supported.
Specifies how to obtain the discount. One of: COUPON.
Coupon to redeem into a discount for this resource. Only required when type = COUPON.
id of the Coupon object.
Whether automatic tax is enabled for this checkout. When enabled, the system attempts to calculate taxes for this checkout's invoice automatically.
Time when the Checkout Session expires.
ID of the Checkout Session object.
A list of items the customer is purchasing.
List of discounts applied to the line item. Discounts of line items are applied before subscription or invoice discounts. Currently, only one element is supported.
Specifies how to obtain the discount. One of: COUPON.
Coupon to redeem into a discount for this resource. Only required when type = COUPON.
id of the Coupon object.
ID of the Price object.
The quantity of the line item being purchased.
The effective tax percent of this line item.
The mode of the Checkout Session object, can be one of:
PAYMENT: Accept one-off payments.SUBSCRIPTION: Set up subscriptions.SETUP: Collect payment details to charge your customers later.
The status of the Checkout Session object, can be one of:
ACTIVE: The Checkout Session is available for the customer to complete a purchase.COMPLETED: The Checkout Session has been completed.CANCELLED: The Checkout Session has been cancelled.EXPIRED: The Checkout Session has expired.
The status automatically changes from ACTIVE to EXPIRED after 1 hour if purchase has not been completed.
The UI mode of the Checkout Session, can be one of:
HOSTED: Customers complete the checkout on an Airwallex-hosted page.
EMBEDDED: Embed the checkout UI directly in your website or app.
ELEMENTS: Build a custom checkout UI using Airwallex Elements.
Time when the Checkout Session was last updated.
If set, the hosted checkout page displays a back button which allows customers to cancel the flow and be directed to this URL.
ID of the Billing Customer associated with this Checkout Session, if applicable.
Time when the Checkout Session was cancelled.
The client secret used to initialize the Checkout Session in EMBEDDED or ELEMENTS ui_mode. Only present when ui_mode is EMBEDDED or ELEMENTS.
Time when the Checkout Session was completed.
The checkout currency in 3-letter ISO-4217 format.
The prefilled information of the customer.
Two-letter ISO 3166 country code of the shopper's country. Strongly recommended — drives which payment methods are surfaced (iDEAL / EPS etc. are country-restricted). Falls back to IP geo when absent.
The prefilled email of the customer.
If this field, or a customer_id or billing_customer_id with an email on file, is provided, the email will be prefilled and will not be editable during checkout.
If no email is provided, the Checkout Session prompts the customer to enter their email.
The prefilled name of the customer.
If this field, or a customer_id or billing_customer_id with a name on file, is provided, the name will be prefilled and will not be editable during checkout.
If no name is provided, the Checkout Session prompts the customer to enter their name.
Type of the customer, one of BUSINESS or INDIVIDUAL. If not provided and no type is available from an existing customer, an "I am purchasing as a business" checkbox is displayed for the customer to self-select.
Provides configuration for the Checkout Session to collect information from customers.
Controls whether the billing address will be collected during checkout.
AUTO: Billing address is collected only when necessary, including when automatic tax is enabled or a tax ID is collected.REQUIRED: Billing address is always collected. Defaults toAUTO.
Controls whether the email address will be collected during checkout.
AUTO: Email address is collected only when necessary, including when an invoice is created or when required by the selected payment method.REQUIRED: Email address is always collected.
AUTOREQUIREDControls whether the name will be collected during checkout.
AUTO: Name is collected only when necessary, including when an invoice is created or when required by the selected payment method.REQUIRED: Name is always collected.
AUTOREQUIREDControls whether the phone number will be collected during checkout.
AUTO: Phone number is collected only when necessary.REQUIRED: Phone number is always collected.
AUTOREQUIREDControls whether the tax ID will be collected for a business customer during checkout.
DISABLED: Tax ID will not be collected.OPTIONAL_IF_SUPPORTED: Tax ID is optionally collected in supported countries by displaying the "I am purchasing as a business" checkbox.REQUIRED_IF_SUPPORTED: Tax ID is always collected when the country is supported. Defaults toOPTIONAL_IF_SUPPORTED.
ID of the Customer from the Payments API associated with this Checkout Session, if applicable.
Configuration of the customer experience after the Checkout Session completes. Only applicable when ui_mode is HOSTED.
Whether to display the Airwallex-hosted completion page after the Checkout Session completes and before the customer is redirected to success_url.
Invoice creation settings for this Checkout Session.
Whether an invoice is created for this Checkout Session.
The invoice settings used for this Checkout Session.
Number of days from invoice finalization until payment is due.
The tax rate between 0 and 100(%) to be applied to invoices to be generated. The tax will be exclusive. Defaults to 0.
Due date set by the merchant for this invoice, if any.
String used for merchants to share a custom message to their customers. Referenced as memo or invoice note in Webapp.
A set of key-value pairs that you can attach to this object for storing additional information.
ID of the invoice for the Checkout Session when mode is PAYMENT. Only applicable when status is COMPLETED.
ID of the legal entity to be used as billing entity, which can be retrieved from the legal_entity_id field in the Retrieve account details API response.
The locale for the Checkout Session.
A set of string key-value pairs that you can attach to this object for storing additional information.
ID of the Payment Consent created when the Checkout Session is completed.
The Payment Intent parameters configured for this Checkout Session.
Descriptor that will display to the customer on their bank statement. Maximum length is 32. Only applicable when mode is PAYMENT.
The order unique identifier created in merchant's order system that corresponds to this Payment Intent. Maximum length is 64.
Shipping information.
Shipping address.
The two-letter country code in ISO 3166-1 alpha-2 format.
City of the address.
Postcode of the address.
State or province of the address.
Street address.
Shipping fee amount.
First name of the recipient. Maximum of 128 characters.
Last name of the recipient. Maximum of 128 characters.
Phone number of the recipient. Maximum of 50 characters.
Use if customer chose to deliver the item at a later time. The timestamp must include an explicit timezone, for example Z or -04:00.
Shipping method for the product. Maximum of 128 characters.
ID of the Payment Intent associated with this Checkout Session.
Payment settings of this Checkout Session.
One or more card networks that you support. Accepted values are visa, mastercard, maestro, unionpay, amex, jcb, diners, and discover. Only applicable when mode is PAYMENT.
Whether the amount should be captured automatically upon successful payment authorization. Set to false to place a hold on the payment method and capture the funds later. Defaults to true. Only applicable when mode is PAYMENT.
Enables the option to "Request an invoice" for payment. After the customer confirms to pay with this option, the status of Checkout Session will transit to COMPLETED, and an invoice will be generated. The invoice will inherit the payment_options of this Checkout Session, and other configurations in invoice_creation.invoice_data. Only applicable when an invoice is created, and the customer type is BUSINESS.
Settings that control whether and how the payment method can be reused for future payments.
Whether and how to store the payment method used in this Checkout Session for future payments. Accepted values:
ENABLED: Always store the payment method when possible; no checkbox is shown.DISABLED: Never store the payment method; always treat the transaction as guest checkout.COLLECT_CONSENT: Show a checkbox and only store the payment method if the customer explicitly opts in. Only applicable to cards.
Indicates who will use the saved Payment Source or Payment Consent to trigger future payments. One of MERCHANT or CUSTOMER.
If MERCHANT, a Payment Source or Payment Consent is created for future use. If CUSTOMER, the payment method is saved only with the payment provider.
Specify which payment methods to display on the Checkout Page and set their display order. Only methods supported for the specified currency and the customer's country code will appear on the Checkout Page. If omitted, all available payment methods are displayed in the default order.
Possible values when mode is SUBSCRIPTION: card, applepay, googlepay, alipaycn, alipayhk, dana, gcash, kakaopay, klarna, rabbit_line_pay, tng, truemoney.
Possible values when mode is PAYMENT: card, applepay, googlepay, wechatpay, alipaycn, alipayhk, gcash, dana, kakaopay, tng, truemoney, bkash, poli, fpx, bank_transfer, alfamart, doku_ewallet, enets, grabpay, indomaret, konbini, online_banking, payeasy, payeasy_atm, seven_eleven, skrill, tesco_lotus, eps, giropay, bancontact, ideal, multibanco, p24, sofort, trustly, dragonpay, blik, mybank, paybybankapp, safetypay, verkkopankki, maxima, narvesen, paypost, perlas_terminals, paysafecash, paysafecard, paysera, satispay, family_mart, hi_life, permata_atm, sam_kiosk, axs_kiosk, esun, shopee_pay, boost, paypal, payu, bitpay, ovo, rabbit_line_pay, ach_direct_debit, bacs_direct_debit, becs_direct_debit, sepa_direct_debit, eft_direct_debit, atome, go_pay, jenius_pay, linkaja, duit_now, pay_now, prompt_pay, airwallex_pay, fps, klarna, korean_local_card, payco, samsung_pay, naver_pay, toss_pay, upi, line_pay, paypay, merpay, d_barai, au_pay, rakuten_pay, zip, spei, afterpay, airi, lumi, payto, twint, venmo, pix, laybuy, cash_app_pay, payme, octopus, tabby, spaylater, wero, jkopay, affirm, bizum, cartes_bancaires, swish, mbway.
Possible values when mode is SETUP: card.
ID of the Payment Source created when the Checkout Session is completed.
The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method's app or site, with payment status not confirmed.
The settings of subscription to be passed to the subscription creation upon completion of the Checkout Session in SUBSCRIPTION mode.
Number of days from invoice finalization until payment is due. Defaults to 0.
The billing cycle for recurring charges.
The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
Invoices for the Subscription will be created using the specified settings.
Memo to be used for the invoices that are generated by this Subscription.
The tax rate between 0 and 100(%) to be applied to invoices to be generated. The tax will be exclusive. Defaults to 0.
The total duration of the subscription.
The number of period units.
Specifies billing duration. One of DAY, WEEK, MONTH or YEAR.
A set of string key-value pairs that you can attach to this object for storing additional information.
Time when the subscription started or scheduled to start. Defaults to start immediately after creation.
The end time of the trial if applicable.
ID of the subscription for the Checkout Session when mode is SUBSCRIPTION. Only applicable when status is COMPLETED.
The URL the customer will be directed to after the checkout completion.
Customization options for the Checkout Page.
The layout of the Checkout Page.
Specify the layout for the payment elements. Accepted values are tab and accordion. By default, accordion layout is used on desktop and tab layout is used on mobile. Only applicable when no invoice is created.
Describes the type of transaction being performed in order to customize the submit button text. Accepted values are pay, book, subscribe, and save.
ID of the theme to apply to this Checkout Session, overriding the theme applied to its legal entity. You can find this ID in the Airwallex web app > Settings > Themes.
The URL to the Checkout Session. Only present when status is ACTIVE.
The page cursor used for searching after page.
The page cursor used for search before page.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request GET \> --url 'https://api.sandbox.airwallex.com/api/v1/checkout/checkout_sessions' \> --header 'Authorization: Bearer <token>' \> --header 'Content-Type: application/json'
1{2 "items": [3 {4 "automatic_tax_status": "DISABLED",5 "created_at": "2025-05-10T16:00:30+0000",6 "discounts": [],7 "enable_automatic_tax": false,8 "expires_at": "2025-05-10T17:00:30+0000",9 "id": "bco_sgstcdcpnh8sv3awiwo",10 "mode": "PAYMENT",11 "status": "ACTIVE",12 "success_url": "https://www.airwallex.com/success",13 "ui_mode": "HOSTED",14 "updated_at": "2025-05-10T16:00:30+0000",15 "account_id": "acct_ncI2nypPKSq2VXKxscAcg",16 "currency": "USD",17 "customer_id": "cus_hkpd7fedfgb004apkvs",18 "line_items": [19 {20 "price_id": "pri_hkpd7fedfgb004apkvs",21 "discounts": [],22 "quantity": 123 }24 ],25 "url": "https://checkout.airwallex.com/pay?s=jwt_token"26 }27 ],28 "page_after": "<string>",29 "page_before": "<string>"30}
Update a Checkout SessionEarly access
POST /api/v1/checkout/checkout_sessions/{id}/update
Updates a Checkout Session object.
ID of the Checkout Session
A set of string key-value pairs that you can attach to this object for storing additional information.
ID of the Airwallex payment account used to collect payment. You can find this ID in the Airwallex web app > Settings > Account details, within the Account Information section.
The automatic tax status of this checkout. One of:
APPLIED: The automatic tax is applied.DISABLED: The automatic tax is disabled.LOCATION_NOT_SUPPORTED: Automatic tax calculation isn't supported in the customer's location.LOCATION_NOT_REGISTERED_BY_MERCHANT: The merchant isn't registered to collect tax in the customer's location.ADDRESS_INCOMPLETE: The customer address was insufficient or invalid to determine the correct tax.
APPLIEDDISABLEDLOCATION_NOT_SUPPORTEDLOCATION_NOT_REGISTERED_BY_MERCHANTADDRESS_INCOMPLETEIf set, the hosted checkout page displays a back button which allows customers to cancel the flow and be directed to this URL.
ID of the Billing Customer associated with this Checkout Session, if applicable.
Time when the Checkout Session was cancelled.
The client secret used to initialize the Checkout Session in EMBEDDED or ELEMENTS ui_mode. Only present when ui_mode is EMBEDDED or ELEMENTS.
Time when the Checkout Session was completed.
Time when the Checkout Session was created.
The checkout currency in 3-letter ISO-4217 format.
The prefilled information of the customer.
Two-letter ISO 3166 country code of the shopper's country. Strongly recommended — drives which payment methods are surfaced (iDEAL / EPS etc. are country-restricted). Falls back to IP geo when absent.
The prefilled email of the customer.
If this field, or a customer_id or billing_customer_id with an email on file, is provided, the email will be prefilled and will not be editable during checkout.
If no email is provided, the Checkout Session prompts the customer to enter their email.
The prefilled name of the customer.
If this field, or a customer_id or billing_customer_id with a name on file, is provided, the name will be prefilled and will not be editable during checkout.
If no name is provided, the Checkout Session prompts the customer to enter their name.
Type of the customer, one of BUSINESS or INDIVIDUAL. If not provided and no type is available from an existing customer, an "I am purchasing as a business" checkbox is displayed for the customer to self-select.
Provides configuration for the Checkout Session to collect information from customers.
Controls whether the billing address will be collected during checkout.
AUTO: Billing address is collected only when necessary, including when automatic tax is enabled or a tax ID is collected.REQUIRED: Billing address is always collected. Defaults toAUTO.
Controls whether the email address will be collected during checkout.
AUTO: Email address is collected only when necessary, including when an invoice is created or when required by the selected payment method.REQUIRED: Email address is always collected.
AUTOREQUIREDControls whether the name will be collected during checkout.
AUTO: Name is collected only when necessary, including when an invoice is created or when required by the selected payment method.REQUIRED: Name is always collected.
AUTOREQUIREDControls whether the phone number will be collected during checkout.
AUTO: Phone number is collected only when necessary.REQUIRED: Phone number is always collected.
AUTOREQUIREDControls whether the tax ID will be collected for a business customer during checkout.
DISABLED: Tax ID will not be collected.OPTIONAL_IF_SUPPORTED: Tax ID is optionally collected in supported countries by displaying the "I am purchasing as a business" checkbox.REQUIRED_IF_SUPPORTED: Tax ID is always collected when the country is supported. Defaults toOPTIONAL_IF_SUPPORTED.
ID of the Customer from the Payments API associated with this Checkout Session, if applicable.
List of discounts applied to the subscription or invoice. Discounts of line items are applied before subscription or invoice discounts. Currently, only one element is supported.
Specifies how to obtain the discount. One of: COUPON.
Coupon to redeem into a discount for this resource. Only required when type = COUPON.
id of the Coupon object.
Whether automatic tax is enabled for this checkout. When enabled, the system attempts to calculate taxes for this checkout's invoice automatically.
Time when the Checkout Session expires.
Configuration of the customer experience after the Checkout Session completes. Only applicable when ui_mode is HOSTED.
Whether to display the Airwallex-hosted completion page after the Checkout Session completes and before the customer is redirected to success_url.
ID of the Checkout Session object.
Invoice creation settings for this Checkout Session.
Whether an invoice is created for this Checkout Session.
The invoice settings used for this Checkout Session.
Number of days from invoice finalization until payment is due.
The tax rate between 0 and 100(%) to be applied to invoices to be generated. The tax will be exclusive. Defaults to 0.
Due date set by the merchant for this invoice, if any.
String used for merchants to share a custom message to their customers. Referenced as memo or invoice note in Webapp.
A set of key-value pairs that you can attach to this object for storing additional information.
ID of the invoice for the Checkout Session when mode is PAYMENT. Only applicable when status is COMPLETED.
ID of the legal entity to be used as billing entity, which can be retrieved from the legal_entity_id field in the Retrieve account details API response.
A list of items the customer is purchasing.
List of discounts applied to the line item. Discounts of line items are applied before subscription or invoice discounts. Currently, only one element is supported.
Specifies how to obtain the discount. One of: COUPON.
Coupon to redeem into a discount for this resource. Only required when type = COUPON.
id of the Coupon object.
ID of the Price object.
The quantity of the line item being purchased.
The effective tax percent of this line item.
The locale for the Checkout Session.
A set of string key-value pairs that you can attach to this object for storing additional information.
The mode of the Checkout Session object, can be one of:
PAYMENT: Accept one-off payments.SUBSCRIPTION: Set up subscriptions.SETUP: Collect payment details to charge your customers later.
ID of the Payment Consent created when the Checkout Session is completed.
The Payment Intent parameters configured for this Checkout Session.
Descriptor that will display to the customer on their bank statement. Maximum length is 32. Only applicable when mode is PAYMENT.
The order unique identifier created in merchant's order system that corresponds to this Payment Intent. Maximum length is 64.
Shipping information.
Shipping address.
The two-letter country code in ISO 3166-1 alpha-2 format.
City of the address.
Postcode of the address.
State or province of the address.
Street address.
Shipping fee amount.
First name of the recipient. Maximum of 128 characters.
Last name of the recipient. Maximum of 128 characters.
Phone number of the recipient. Maximum of 50 characters.
Use if customer chose to deliver the item at a later time. The timestamp must include an explicit timezone, for example Z or -04:00.
Shipping method for the product. Maximum of 128 characters.
ID of the Payment Intent associated with this Checkout Session.
Payment settings of this Checkout Session.
One or more card networks that you support. Accepted values are visa, mastercard, maestro, unionpay, amex, jcb, diners, and discover. Only applicable when mode is PAYMENT.
Whether the amount should be captured automatically upon successful payment authorization. Set to false to place a hold on the payment method and capture the funds later. Defaults to true. Only applicable when mode is PAYMENT.
Enables the option to "Request an invoice" for payment. After the customer confirms to pay with this option, the status of Checkout Session will transit to COMPLETED, and an invoice will be generated. The invoice will inherit the payment_options of this Checkout Session, and other configurations in invoice_creation.invoice_data. Only applicable when an invoice is created, and the customer type is BUSINESS.
Settings that control whether and how the payment method can be reused for future payments.
Whether and how to store the payment method used in this Checkout Session for future payments. Accepted values:
ENABLED: Always store the payment method when possible; no checkbox is shown.DISABLED: Never store the payment method; always treat the transaction as guest checkout.COLLECT_CONSENT: Show a checkbox and only store the payment method if the customer explicitly opts in. Only applicable to cards.
Indicates who will use the saved Payment Source or Payment Consent to trigger future payments. One of MERCHANT or CUSTOMER.
If MERCHANT, a Payment Source or Payment Consent is created for future use. If CUSTOMER, the payment method is saved only with the payment provider.
Specify which payment methods to display on the Checkout Page and set their display order. Only methods supported for the specified currency and the customer's country code will appear on the Checkout Page. If omitted, all available payment methods are displayed in the default order.
Possible values when mode is SUBSCRIPTION: card, applepay, googlepay, alipaycn, alipayhk, dana, gcash, kakaopay, klarna, rabbit_line_pay, tng, truemoney.
Possible values when mode is PAYMENT: card, applepay, googlepay, wechatpay, alipaycn, alipayhk, gcash, dana, kakaopay, tng, truemoney, bkash, poli, fpx, bank_transfer, alfamart, doku_ewallet, enets, grabpay, indomaret, konbini, online_banking, payeasy, payeasy_atm, seven_eleven, skrill, tesco_lotus, eps, giropay, bancontact, ideal, multibanco, p24, sofort, trustly, dragonpay, blik, mybank, paybybankapp, safetypay, verkkopankki, maxima, narvesen, paypost, perlas_terminals, paysafecash, paysafecard, paysera, satispay, family_mart, hi_life, permata_atm, sam_kiosk, axs_kiosk, esun, shopee_pay, boost, paypal, payu, bitpay, ovo, rabbit_line_pay, ach_direct_debit, bacs_direct_debit, becs_direct_debit, sepa_direct_debit, eft_direct_debit, atome, go_pay, jenius_pay, linkaja, duit_now, pay_now, prompt_pay, airwallex_pay, fps, klarna, korean_local_card, payco, samsung_pay, naver_pay, toss_pay, upi, line_pay, paypay, merpay, d_barai, au_pay, rakuten_pay, zip, spei, afterpay, airi, lumi, payto, twint, venmo, pix, laybuy, cash_app_pay, payme, octopus, tabby, spaylater, wero, jkopay, affirm, bizum, cartes_bancaires, swish, mbway.
Possible values when mode is SETUP: card.
ID of the Payment Source created when the Checkout Session is completed.
The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method's app or site, with payment status not confirmed.
The status of the Checkout Session object, can be one of:
ACTIVE: The Checkout Session is available for the customer to complete a purchase.COMPLETED: The Checkout Session has been completed.CANCELLED: The Checkout Session has been cancelled.EXPIRED: The Checkout Session has expired.
The status automatically changes from ACTIVE to EXPIRED after 1 hour if purchase has not been completed.
The settings of subscription to be passed to the subscription creation upon completion of the Checkout Session in SUBSCRIPTION mode.
Number of days from invoice finalization until payment is due. Defaults to 0.
The billing cycle for recurring charges.
The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
Invoices for the Subscription will be created using the specified settings.
Memo to be used for the invoices that are generated by this Subscription.
The tax rate between 0 and 100(%) to be applied to invoices to be generated. The tax will be exclusive. Defaults to 0.
The total duration of the subscription.
The number of period units.
Specifies billing duration. One of DAY, WEEK, MONTH or YEAR.
A set of string key-value pairs that you can attach to this object for storing additional information.
Time when the subscription started or scheduled to start. Defaults to start immediately after creation.
The end time of the trial if applicable.
ID of the subscription for the Checkout Session when mode is SUBSCRIPTION. Only applicable when status is COMPLETED.
The URL the customer will be directed to after the checkout completion.
The UI mode of the Checkout Session, can be one of:
HOSTED: Customers complete the checkout on an Airwallex-hosted page.
EMBEDDED: Embed the checkout UI directly in your website or app.
ELEMENTS: Build a custom checkout UI using Airwallex Elements.
Customization options for the Checkout Page.
The layout of the Checkout Page.
Specify the layout for the payment elements. Accepted values are tab and accordion. By default, accordion layout is used on desktop and tab layout is used on mobile. Only applicable when no invoice is created.
Describes the type of transaction being performed in order to customize the submit button text. Accepted values are pay, book, subscribe, and save.
ID of the theme to apply to this Checkout Session, overriding the theme applied to its legal entity. You can find this ID in the Airwallex web app > Settings > Themes.
Time when the Checkout Session was last updated.
The URL to the Checkout Session. Only present when status is ACTIVE.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/checkout/checkout_sessions/checkout_session_id/update' \> --header 'Authorization: Bearer <token>' \> --header 'Content-Type: application/json' \> --data '{> "metadata": {> "foo": "bar"> }>}'
1{2 "automatic_tax_status": "DISABLED",3 "created_at": "2025-05-10T16:00:30+0000",4 "discounts": [],5 "enable_automatic_tax": false,6 "expires_at": "2025-05-10T17:00:30+0000",7 "id": "bco_sgstcdcpnh8sv3awiwo",8 "mode": "PAYMENT",9 "status": "ACTIVE",10 "success_url": "https://www.airwallex.com/success",11 "ui_mode": "HOSTED",12 "updated_at": "2025-05-10T16:05:30+0000",13 "account_id": "acct_ncI2nypPKSq2VXKxscAcg",14 "currency": "USD",15 "customer_id": "cus_hkpd7fedfgb004apkvs",16 "line_items": [17 {18 "price_id": "pri_hkpd7fedfgb004apkvs",19 "discounts": [],20 "quantity": 121 }22 ],23 "metadata": {24 "foo": "bar"25 },26 "url": "https://checkout.airwallex.com/pay?s=jwt_token"27}
Cancel a Checkout SessionEarly access
POST /api/v1/checkout/checkout_sessions/{id}/cancel
Cancels an ACTIVE Checkout Session. Once cancelled, the customer will no longer be able to complete the checkout and will see an error message when attempting to load it.
ID of the Checkout Session
ID of the Airwallex payment account used to collect payment. You can find this ID in the Airwallex web app > Settings > Account details, within the Account Information section.
The automatic tax status of this checkout. One of:
APPLIED: The automatic tax is applied.DISABLED: The automatic tax is disabled.LOCATION_NOT_SUPPORTED: Automatic tax calculation isn't supported in the customer's location.LOCATION_NOT_REGISTERED_BY_MERCHANT: The merchant isn't registered to collect tax in the customer's location.ADDRESS_INCOMPLETE: The customer address was insufficient or invalid to determine the correct tax.
APPLIEDDISABLEDLOCATION_NOT_SUPPORTEDLOCATION_NOT_REGISTERED_BY_MERCHANTADDRESS_INCOMPLETEIf set, the hosted checkout page displays a back button which allows customers to cancel the flow and be directed to this URL.
ID of the Billing Customer associated with this Checkout Session, if applicable.
Time when the Checkout Session was cancelled.
The client secret used to initialize the Checkout Session in EMBEDDED or ELEMENTS ui_mode. Only present when ui_mode is EMBEDDED or ELEMENTS.
Time when the Checkout Session was completed.
Time when the Checkout Session was created.
The checkout currency in 3-letter ISO-4217 format.
The prefilled information of the customer.
Two-letter ISO 3166 country code of the shopper's country. Strongly recommended — drives which payment methods are surfaced (iDEAL / EPS etc. are country-restricted). Falls back to IP geo when absent.
The prefilled email of the customer.
If this field, or a customer_id or billing_customer_id with an email on file, is provided, the email will be prefilled and will not be editable during checkout.
If no email is provided, the Checkout Session prompts the customer to enter their email.
The prefilled name of the customer.
If this field, or a customer_id or billing_customer_id with a name on file, is provided, the name will be prefilled and will not be editable during checkout.
If no name is provided, the Checkout Session prompts the customer to enter their name.
Type of the customer, one of BUSINESS or INDIVIDUAL. If not provided and no type is available from an existing customer, an "I am purchasing as a business" checkbox is displayed for the customer to self-select.
Provides configuration for the Checkout Session to collect information from customers.
Controls whether the billing address will be collected during checkout.
AUTO: Billing address is collected only when necessary, including when automatic tax is enabled or a tax ID is collected.REQUIRED: Billing address is always collected. Defaults toAUTO.
Controls whether the email address will be collected during checkout.
AUTO: Email address is collected only when necessary, including when an invoice is created or when required by the selected payment method.REQUIRED: Email address is always collected.
AUTOREQUIREDControls whether the name will be collected during checkout.
AUTO: Name is collected only when necessary, including when an invoice is created or when required by the selected payment method.REQUIRED: Name is always collected.
AUTOREQUIREDControls whether the phone number will be collected during checkout.
AUTO: Phone number is collected only when necessary.REQUIRED: Phone number is always collected.
AUTOREQUIREDControls whether the tax ID will be collected for a business customer during checkout.
DISABLED: Tax ID will not be collected.OPTIONAL_IF_SUPPORTED: Tax ID is optionally collected in supported countries by displaying the "I am purchasing as a business" checkbox.REQUIRED_IF_SUPPORTED: Tax ID is always collected when the country is supported. Defaults toOPTIONAL_IF_SUPPORTED.
ID of the Customer from the Payments API associated with this Checkout Session, if applicable.
List of discounts applied to the subscription or invoice. Discounts of line items are applied before subscription or invoice discounts. Currently, only one element is supported.
Specifies how to obtain the discount. One of: COUPON.
Coupon to redeem into a discount for this resource. Only required when type = COUPON.
id of the Coupon object.
Whether automatic tax is enabled for this checkout. When enabled, the system attempts to calculate taxes for this checkout's invoice automatically.
Time when the Checkout Session expires.
Configuration of the customer experience after the Checkout Session completes. Only applicable when ui_mode is HOSTED.
Whether to display the Airwallex-hosted completion page after the Checkout Session completes and before the customer is redirected to success_url.
ID of the Checkout Session object.
Invoice creation settings for this Checkout Session.
Whether an invoice is created for this Checkout Session.
The invoice settings used for this Checkout Session.
Number of days from invoice finalization until payment is due.
The tax rate between 0 and 100(%) to be applied to invoices to be generated. The tax will be exclusive. Defaults to 0.
Due date set by the merchant for this invoice, if any.
String used for merchants to share a custom message to their customers. Referenced as memo or invoice note in Webapp.
A set of key-value pairs that you can attach to this object for storing additional information.
ID of the invoice for the Checkout Session when mode is PAYMENT. Only applicable when status is COMPLETED.
ID of the legal entity to be used as billing entity, which can be retrieved from the legal_entity_id field in the Retrieve account details API response.
A list of items the customer is purchasing.
List of discounts applied to the line item. Discounts of line items are applied before subscription or invoice discounts. Currently, only one element is supported.
Specifies how to obtain the discount. One of: COUPON.
Coupon to redeem into a discount for this resource. Only required when type = COUPON.
id of the Coupon object.
ID of the Price object.
The quantity of the line item being purchased.
The effective tax percent of this line item.
The locale for the Checkout Session.
A set of string key-value pairs that you can attach to this object for storing additional information.
The mode of the Checkout Session object, can be one of:
PAYMENT: Accept one-off payments.SUBSCRIPTION: Set up subscriptions.SETUP: Collect payment details to charge your customers later.
ID of the Payment Consent created when the Checkout Session is completed.
The Payment Intent parameters configured for this Checkout Session.
Descriptor that will display to the customer on their bank statement. Maximum length is 32. Only applicable when mode is PAYMENT.
The order unique identifier created in merchant's order system that corresponds to this Payment Intent. Maximum length is 64.
Shipping information.
Shipping address.
The two-letter country code in ISO 3166-1 alpha-2 format.
City of the address.
Postcode of the address.
State or province of the address.
Street address.
Shipping fee amount.
First name of the recipient. Maximum of 128 characters.
Last name of the recipient. Maximum of 128 characters.
Phone number of the recipient. Maximum of 50 characters.
Use if customer chose to deliver the item at a later time. The timestamp must include an explicit timezone, for example Z or -04:00.
Shipping method for the product. Maximum of 128 characters.
ID of the Payment Intent associated with this Checkout Session.
Payment settings of this Checkout Session.
One or more card networks that you support. Accepted values are visa, mastercard, maestro, unionpay, amex, jcb, diners, and discover. Only applicable when mode is PAYMENT.
Whether the amount should be captured automatically upon successful payment authorization. Set to false to place a hold on the payment method and capture the funds later. Defaults to true. Only applicable when mode is PAYMENT.
Enables the option to "Request an invoice" for payment. After the customer confirms to pay with this option, the status of Checkout Session will transit to COMPLETED, and an invoice will be generated. The invoice will inherit the payment_options of this Checkout Session, and other configurations in invoice_creation.invoice_data. Only applicable when an invoice is created, and the customer type is BUSINESS.
Settings that control whether and how the payment method can be reused for future payments.
Whether and how to store the payment method used in this Checkout Session for future payments. Accepted values:
ENABLED: Always store the payment method when possible; no checkbox is shown.DISABLED: Never store the payment method; always treat the transaction as guest checkout.COLLECT_CONSENT: Show a checkbox and only store the payment method if the customer explicitly opts in. Only applicable to cards.
Indicates who will use the saved Payment Source or Payment Consent to trigger future payments. One of MERCHANT or CUSTOMER.
If MERCHANT, a Payment Source or Payment Consent is created for future use. If CUSTOMER, the payment method is saved only with the payment provider.
Specify which payment methods to display on the Checkout Page and set their display order. Only methods supported for the specified currency and the customer's country code will appear on the Checkout Page. If omitted, all available payment methods are displayed in the default order.
Possible values when mode is SUBSCRIPTION: card, applepay, googlepay, alipaycn, alipayhk, dana, gcash, kakaopay, klarna, rabbit_line_pay, tng, truemoney.
Possible values when mode is PAYMENT: card, applepay, googlepay, wechatpay, alipaycn, alipayhk, gcash, dana, kakaopay, tng, truemoney, bkash, poli, fpx, bank_transfer, alfamart, doku_ewallet, enets, grabpay, indomaret, konbini, online_banking, payeasy, payeasy_atm, seven_eleven, skrill, tesco_lotus, eps, giropay, bancontact, ideal, multibanco, p24, sofort, trustly, dragonpay, blik, mybank, paybybankapp, safetypay, verkkopankki, maxima, narvesen, paypost, perlas_terminals, paysafecash, paysafecard, paysera, satispay, family_mart, hi_life, permata_atm, sam_kiosk, axs_kiosk, esun, shopee_pay, boost, paypal, payu, bitpay, ovo, rabbit_line_pay, ach_direct_debit, bacs_direct_debit, becs_direct_debit, sepa_direct_debit, eft_direct_debit, atome, go_pay, jenius_pay, linkaja, duit_now, pay_now, prompt_pay, airwallex_pay, fps, klarna, korean_local_card, payco, samsung_pay, naver_pay, toss_pay, upi, line_pay, paypay, merpay, d_barai, au_pay, rakuten_pay, zip, spei, afterpay, airi, lumi, payto, twint, venmo, pix, laybuy, cash_app_pay, payme, octopus, tabby, spaylater, wero, jkopay, affirm, bizum, cartes_bancaires, swish, mbway.
Possible values when mode is SETUP: card.
ID of the Payment Source created when the Checkout Session is completed.
The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method's app or site, with payment status not confirmed.
The status of the Checkout Session object, can be one of:
ACTIVE: The Checkout Session is available for the customer to complete a purchase.COMPLETED: The Checkout Session has been completed.CANCELLED: The Checkout Session has been cancelled.EXPIRED: The Checkout Session has expired.
The status automatically changes from ACTIVE to EXPIRED after 1 hour if purchase has not been completed.
The settings of subscription to be passed to the subscription creation upon completion of the Checkout Session in SUBSCRIPTION mode.
Number of days from invoice finalization until payment is due. Defaults to 0.
The billing cycle for recurring charges.
The number of period units between subscription billing cycles. For example, the billing cycle is bi-monthly if period=2 and period_unit=MONTH.
Specifies billing frequency. One of DAY, WEEK, MONTH or YEAR.
Invoices for the Subscription will be created using the specified settings.
Memo to be used for the invoices that are generated by this Subscription.
The tax rate between 0 and 100(%) to be applied to invoices to be generated. The tax will be exclusive. Defaults to 0.
The total duration of the subscription.
The number of period units.
Specifies billing duration. One of DAY, WEEK, MONTH or YEAR.
A set of string key-value pairs that you can attach to this object for storing additional information.
Time when the subscription started or scheduled to start. Defaults to start immediately after creation.
The end time of the trial if applicable.
ID of the subscription for the Checkout Session when mode is SUBSCRIPTION. Only applicable when status is COMPLETED.
The URL the customer will be directed to after the checkout completion.
The UI mode of the Checkout Session, can be one of:
HOSTED: Customers complete the checkout on an Airwallex-hosted page.
EMBEDDED: Embed the checkout UI directly in your website or app.
ELEMENTS: Build a custom checkout UI using Airwallex Elements.
Customization options for the Checkout Page.
The layout of the Checkout Page.
Specify the layout for the payment elements. Accepted values are tab and accordion. By default, accordion layout is used on desktop and tab layout is used on mobile. Only applicable when no invoice is created.
Describes the type of transaction being performed in order to customize the submit button text. Accepted values are pay, book, subscribe, and save.
ID of the theme to apply to this Checkout Session, overriding the theme applied to its legal entity. You can find this ID in the Airwallex web app > Settings > Themes.
Time when the Checkout Session was last updated.
The URL to the Checkout Session. Only present when status is ACTIVE.
| Error status | Description |
|---|---|
| 400 | Bad Request. Possible error codes: |
| 401 | Unauthorized. Possible error codes: |
| 404 | Not Found. Possible error codes: |
| 500 | Server Error. Possible error codes: |
$curl --request POST \> --url 'https://api.sandbox.airwallex.com/api/v1/checkout/checkout_sessions/checkout_session_id/cancel' \> --header 'Authorization: Bearer <token>' \> --header 'Content-Type: application/json'
1{2 "automatic_tax_status": "DISABLED",3 "created_at": "2025-05-10T16:00:30+0000",4 "discounts": [],5 "enable_automatic_tax": false,6 "expires_at": "2025-05-10T17:00:30+0000",7 "id": "bco_sgstcdcpnh8sv3awiwo",8 "mode": "PAYMENT",9 "status": "CANCELLED",10 "success_url": "https://www.airwallex.com/success",11 "ui_mode": "HOSTED",12 "updated_at": "2025-05-10T16:10:30+0000",13 "account_id": "acct_ncI2nypPKSq2VXKxscAcg",14 "cancelled_at": "2025-05-10T16:10:30+0000",15 "currency": "USD",16 "customer_id": "cus_hkpd7fedfgb004apkvs",17 "line_items": [18 {19 "price_id": "pri_hkpd7fedfgb004apkvs",20 "discounts": [],21 "quantity": 122 }23 ]24}