Log inGet started
Airwallex logo
Home
Online Payments
Treasury
Transactional FX
Payouts
Issuing
Scale
Open Banking
Developer Tools
API Reference
Home
Online Payments
Overview
Starting with paymentsTransaction and settlement modelPricing model
Features
3D Secure authenticationSave payment details for future payments
Hosted Payment Page
Embedded ElementsRedirect/QR Code ElementDrop-in ElementMobile SDKNative API
Multi-currency pricingFraud managementRiskNetwork TokenizationDisputes

Hosted Payment Page

Hosted Payment Page allows you to save payment details for future payments. To save payment details, Airwallex allows you to create a PaymentConsent, which represents the consent between you and the shopper to use the shopper’s saved payment details for future payments.

PaymentConsents may be used to trigger different payment scenarios:

  • Customer-initiated subsequent payments: This is useful for recurring shoppers who can make payments by selecting the saved payment method. For saved cards, the shopper can optionally enter their security code (CVC) for verification to complete the payment.

  • Merchant-initiated subsequent payments: You as a merchant can initiate scheduled (recurring) or unscheduled (one-time) payments without the shopper involved.

This page describes how to save payment details using a Hosted Payment Page integration.

Before you begin

Before you implement the integration, consider the following:

Create a PaymentConsent

You can choose to create and verify a PaymentConsent using the recurringOptions object in redirectToCheckout() when the shopper creates an account with your business or when the shopper makes a payment for the first time.

Configuring recurringOptions is only required for saving card details.

Depending on the scenario, provide the required fields using the recurringOptions object to save card details.

JavaScript

For customer-initiated payments

PropsRequired?TypeDescription
next_triggered_byYesstringSet this to customer
requires_cvcYesbooleanSet to false by default. Indicates whether shopper must enter their CVC when making subsequent payments using saved card details.
currencyYesstringThe three-letter ISO currency code representing the currency of the initial PaymentIntent to verify the PaymentConsent

For merchant-initiated payments

PropsRequired?TypeDescription
next_triggered_byYesstringSet this to merchant
merchant_trigger_reasonYesstringThe reason why you triggered the payment, set to scheduled or unscheduled.
currencyYesstringThe three-letter ISO currency code representing the currency of the initial PaymentIntent to verify the PaymentConsent.

Save payment details without a payment

You can save a shopper’s payment method without an initial payment and charge the shopper later. This is helpful if you want to first onboard shoppers, save their payment details, and then initiate payments (recurring or one-time) in the future without the shopper involved.

This integration is also helpful to the shopper to make future payments using saved payment details.

Step 1: Create a Customer

To set a card up for future payments, you must first store the card on a Customer object. Create a Customer object using Create a Customer API API when your shopper creates an account with your business. You can also store name, email and other details on the Customer. The response will contain a unique id for the shopper.

Step 2: Generate a client secret for the Customer

Provide the Customer id in Generate a client secret for a Customer API API and save the returned client_secret

Step 3: Create a PaymentConsent

Create a checkout page with a redirect button to Hosted Payment Page by passing the following fields in redirectToCheckout():

  • client_secret from Step 2

  • currency

  • customer_id: The id of the Customer for whom the PaymentConsent is created.

  • mode: Set this to recurring

  • recurringOptions: Provide the required values depending on the scenario.

After the PaymentConsent is successfully verified, Airwallex automatically attaches the payment details (in a PaymentMethod object) to your Customer.

Save payment details during payment

You can save shopper’s payment details from a purchase. Some scenarios include saving payment details for future payments with the shopper or to initiate the first payment of a series of recurring payments.

Step 1: Create a Customer

To set a card up for future payments, you must first store the card on a Customer object. Create a Customer object using Create a Customer API API when your shopper creates an account with your business. You can also store name, email and other details on the Customer. The response will contain a unique id for the shopper.

Step 2: Create a PaymentIntent

Call Create a PaymentIntent API API by providing the amount, currency, and id of the shopper in the customer_id parameter. Save the returned intent id and client_secret.

Step 3: Create a PaymentConsent

Create a checkout page with a redirect button to Hosted Payment Page by passing the following fields in redirectToCheckout():

  • intent_id from Step 2
  • client_secret from Step 2
  • currency
  • customer_id: The id of the Customer for whom the PaymentConsent is created.
  • mode: Set this to payment. By default, recurringOptions.card.next_trigger_by is set to customer and recurringOptions.card.requires_cvc is set to true

After the PaymentIntent succeeds, Airwallex automatically attaches the payment details (in a PaymentMethod object) to your Customer.

Customer-initiated subsequent payments

Follow these integration steps to accept customer-initiated subsequent payments.

Step 1: Create a PaymentIntent

Call Create a PaymentIntent API API by providing the amount, currency, and id of the shopper in the customer_id parameter. Save the returned intent id and client_secret.

Step 2: Confirm the PaymentIntent

Create a checkout page with a redirect button to Hosted Payment Page to collect payment details. The list of PaymentConsents associated with your Customer will be displayed on the checkout page for selection. This allows the shopper to choose their preferred PaymentConsent for the payment. For a saved card, the shopper will be prompted to enter their CVC of the card as an additional fraud measure to verify the shopper.

Call createElement( ) with the following fields when the shopper pays with a saved payment method.

  • intent_id: The id of the PaymentIntent you want to confirm and complete.

  • client_secret: The client_secret of the PaymentIntent you want to confirm and complete.

  • customer_id: The id of the Customer for whom the PaymentConsent is created.

A payment may succeed even with a failed CVC check. To prevent this, configure your Risk management rules to block payments when CVC verification fails.

Merchant-initiated subsequent payments

Follow these integration steps to trigger subsequent payments using saved payment details. Note that you must integrate subscription management into your application to initiate scheduled payments at set intervals for an agreed amount.

Step 1: Create a PaymentIntent

Call Create a PaymentIntent API API by providing the amount, currency, and id of the shopper in the customer_id parameter. Save the returned intent id and client_secret.

Step 2: Confirm the PaymentIntent

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

  • intent_id: The id of the PaymentIntent you want to confirm and complete.

  • client_secret: The client_secret of the PaymentIntent you want to confirm and complete.

  • customer_id: The id of the Customer associated with the saved payment method.

  • payment_consent_reference.id: The PaymentConsent id associated with the saved payment method.

On this page