Registered user checkout
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:
Ensure your Airwallex account has been activated for online payments.
Obtain your access token API by authenticating to Airwallex using your unique Client ID and API key. You will need the access token to make API calls.
Read the
airwallex-payment-elementsJavaScript client library reference JS to familiarize yourself with the Hosted Payment Page methods, parameters, and properties.Install the package
- Using Yarn or NPM
yarn add airwallex-payment-elementsnpm install airwallex-payment-elements
- Using CDN
<script src="https://checkout.airwallex.com/assets/elements.bundle.min.js"></script>
- Using Yarn or NPM
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.
For customer-initiated payments
| Props | Required? | Type | Description |
|---|---|---|---|
next_triggered_by | Yes | string | Set this to customer |
currency | Yes | string | The three-letter ISO currency code representing the currency of the initial PaymentIntent to verify the PaymentConsent |
For merchant-initiated payments
| Props | Required? | Type | Description |
|---|---|---|---|
next_triggered_by | Yes | string | Set this to merchant |
merchant_trigger_reason | No | string | The reason why you triggered the payment, set to scheduled or unscheduled. |
currency | Yes | string | The 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 and also the client_secret. Save the client_secret for later.
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_secretfrom Step 2currencycustomer_id: Theidof the Customer for whom the PaymentConsent is created.mode: Set this torecurringrecurringOptions: 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 and also the client_secret. Save the client_secret for later.
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_idfrom Step 2client_secretfrom Step 2currencycustomer_id: Theidof the Customer for whom the PaymentConsent is created.mode: Set this topayment. By default,recurringOptions.card.next_trigger_byis set tocustomerandrecurringOptions.card.requires_cvcis set totrue
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 by providing the amount, currency, and id of the shopper in the customer_id parameter. Save the returned intent id.
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: Theidof the PaymentIntent you want to confirm and complete.client_secret: Theclient_secretof the PaymentIntent you want to confirm and complete.customer_id: Theidof 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 by providing the amount, currency, and id of the shopper in the customer_id parameter. Save the returned intent id.
Step 2: Confirm the PaymentIntent
Call Confirm a PaymentIntent API with the following parameters to charge the shopper.
intent_id: Theidof the PaymentIntent you want to confirm and complete.customer_id: Theidof the Customer associated with the saved payment method.payment_consent_id: The PaymentConsentidassociated with the saved payment method.