Hosted Payment Page

The Hosted Payment Page integration allows you to redirect your shoppers to a secure, pre-built payment page hosted by Airwallex where the shopper can submit payment details to make a payment.

redirectToCheckout(props)

Function to redirect the shopper in a Hosted Payment Page(HPP) integration.

Parameters

props

requiredHostPaymentPage

client_secret

requiredstring

The client_secret of the Payment Intent when Payment Intent is provided. Otherwise, this should be the client_secret of the Customer object.

currency

requiredstring

The three-letter ISO currency code representing the currency of the Payment Intent or Payment Consent. Only payment methods supported for the specified currency will be shown on the payment page.

allowedCardNetworks

One or more card networks that you support.

appearance

optionalAppearance

Page appearance customization options for Hosted Payment Page.

applePayRequestOptions

optionalApplePayRequestOptions

Checkout configuration options for Apple Pay.

countryCode

requiredstring

The merchant's two-letter ISO 3166 country code. For example, 'US'.

applicationData

optionalstring

Optional user-defined data.

billingContact

optionalApplePayPaymentContact

Billing contact information for the shopper.

buttonColor

optional'black' | 'white' | 'white-outline'

Indicate the color of the button.

Default: 'black'

buttonType

optionalenum

Supported methods for presenting the Apple Pay button.

A translated button label may appear if a language specified in the viewer's browser matches an available language.

existingPaymentMethodRequired

optionalboolean

Whether the shopper must have an active card provisioned in Apple Pay.

When set to true, the Apple Pay button will only be displayed if the user has an active card in their Apple Pay wallet, checked via ApplePaySession.canMakePaymentsWithActiveCard().

Default: false

lineItems

optionalApplePayLineItem[]

A set of line items that explain recurring payments and/or additional charges.

merchantCapabilities

optional('supports3DS' | 'supportsEMV' | 'supportsCredit' | 'supportsDebit')[]

Payment capabilities supported by the merchant.

If not configured, merchantCapabilities will be based on merchant's account settings.

supports3DS: Required. This value must be supplied.
supportsCredit: Optional. If present, only transactions that are categorized as credit cards are allowed.
supportsDebit: Optional. If present, only transactions that are categorized as debit cards are allowed.
supportsEMV: Include this value only if you support China Union Pay transactions. (if supportedNetworks does not contain chinaUnionPay, don't include it).

requiredBillingContactFields

optional'postalAddress'[]

The billing information that you require from the shopper in order to process the transaction. Only postalAddress is supported. If you need to collect name, email, phone, you need to add requiredShippingContactFields config. e.g. requiredShippingContactFields: ['name', 'email', 'phone']

requiredShippingContactFields

optional('email' | 'name' | 'phone' | 'postalAddress' | 'phoneticName')[]

The shipping information that you require from the shopper in order to fulfill the order.

shippingContact

optionalApplePayPaymentContact

Shipping contact information for the shopper.

shippingMethods

optionalApplePayShippingMethod[]

A set of shipping method objects that describe the available shipping methods.

shippingType

optional'shipping' | 'delivery' | 'storePickup' | 'servicePickup'

An optional value that indicates how purchased items are to be shipped.

supportedCountries

optionalstring[]

A list of ISO 3166 country codes for limiting payments to cards from specific countries.

supportedNetworks

optionalstring[]

Card networks supported by the merchant.

If not configured, supportedNetworks will be based on merchant's account settings.

For more details, see https://developer.apple.com/documentation/apple_pay_on_the_web/applepaypaymentrequest/1916122-supportednetworks

totalPriceLabel

optionalstring

Provide a business name for the label field. Use the same business name that you want displayed for the charge on the shopper's bank or credit card statement. For example, "COMPANY, INC.".

totalPriceType

optional'pending' | 'final'

Indicate whether a line item is final or pending.

If the mode is recurring and if it's a variable subscription, the value should be pending.

Default: 'final'

authorizationType

optional'pre_auth' | 'final_auth'

The authorization type for the card payment. Set it to 'pre_auth' if you want to place a hold on your customer’s card for more than 7 days, i.e., extend the authorization time window. Currently 'pre_auth' is only available when the card brand is Visa or Mastercard. autoCapture will be automatically set to false if you enable 'pre_auth'.

Default: 'final_auth'

autoCapture

optionalboolean

Whether the amount should be captured automatically upon successful payment authorization. Set it to false if you want to place a hold on the payment method and capture the funds sometime later.

Default: true

autoSaveCardForFuturePayments

optionalboolean

Specifies whether the card payment method should be automatically saved for future transactions.

This parameter is only effective in payment mode when a customer_id is provided.

If set to true, the "Save my card for future payments" checkbox will be preselected by default.
If set to false, the checkbox will remain unchecked, requiring the shopper to manually opt in.

Default: true

cancelUrl

optionalstring

The HTTPS URL to redirect shoppers when they choose to go back or cancel the payment. When provided, a back button will be displayed on the Hosted Payment Page allowing the shopper to return to the merchant's site. If not provided, no back button will be shown.

country_code

optionalstring

The two-letter ISO country code of the shopper's country. If the country_code is not provided, we will determine it based on the shopper's IP address. However, some payment methods, such as iDEAL, are only available to shoppers in specific countries. If the shopper is not located in a supported country, the corresponding payment method may not be displayed. To ensure that your customers can successfully complete their payments using the appropriate methods, we strongly recommend that you explicitly pass the country_code to us.

customer_id

optionalstring

The ID of the Customer used in registered user checkout. Refer to Airwallex Client API This field is required when mode is 'recurring'.

cvcRequired

optionalboolean

Whether you require the shopper to provide CVC when they checkout with a network tokenized card.

disableAutoRedirect

optionalboolean

Whether auto redirect to the URL specified by the merchant should be disabled.

Default: false

env

optional'demo' | 'prod'

The Airwallex integration environment your site would like to connect with.

Default: prod

googlePayRequestOptions

optionalGooglePayHppRequestOptions

Checkout configuration options for Google Pay.

countryCode

requiredstring

The two-letter ISO-3166 country code.

allowCreditCards

optionalboolean

Whether a credit card may be used for this transaction.

Default: true

allowedAuthMethods

optionalCardAuthMethod[]

Allowed authentication methods.

Default: ['PAN_ONLY', 'CRYPTOGRAM_3DS']

allowedCardNetworks

One or more card networks that you support.

allowPrepaidCards

optionalboolean

Whether a prepaid card may be used for this transaction.

Default: true

assuranceDetailsRequired

optionalboolean

Set to true if you need information about the validation performed on the returned payment data.

Default: false

billingAddressParameters

optionalBillingAddressParameters

Optional billing address parameters for the returned billing address.

billingAddressRequired

optionalboolean

Whether a billing address is required from the shopper.

Default: false

buttonColor

optionalenum

Specifies the button color of the Google Pay button.

Default: 'default'

buttonSizeMode

optionalenum

Determines how the button's size should change relative to the button's parent element.

Default: 'static'

buttonType

optionalenum

Specifies the text to be displayed within the Google Pay button.

callbackIntents

optionalCallbackIntent[]

List of callbacks that the developer intents to handle. Upon selection by the shopper, these intents can be used to update the request with new data based on that selection (For exmaple, if a shipping option is selected, the developer could update the transactionInfo with new totalPrice and diplayItems).

checkoutOption

optionalCheckoutOption

The options for checkout.

displayItems

optionalDisplayItem[]

Description of a cart item.

emailRequired

optionalboolean

Whether the shopper must provide their email.

Default: false

existingPaymentMethodRequired

optionalboolean

Whether the shopper must use an existing payment method.

Default: false

gatewayMerchantId

optionalstring

The merchant account ID in Airwallex. It is required for Google Pay Express Checkout Element.

merchantInfo

optionalobject

Detailed information about the merchant.

offerInfo

optionalOfferInfo

Offers available for redemption that can be used with the current order.

paymentDataCallbacks

optionalPaymentDataCallbacks

Defines callback methods for handling changed payment data and payment authorized events.

shippingAddressParameters

optionalShippingAddressParameters

Optional shipping address parameters for the returned shipping address.

shippingAddressRequired

optionalboolean

Whether a shipping address is required from the shopper.

Default: false

shippingOptionParameters

optionalShippingOptionParameters

Parameters for shipping option that can be used in this request. Note: This field is currently for web only.

shippingOptionRequired

optionalboolean

Whether a shipping option is required from the shopper.

Note: This field is currently for web only.

Default: false

totalPriceLabel

optionalstring

Total price label of this transaction. The string will be shown as the total price label on the cart modal dialog page. This field is optional, but required if developer wants to show cart information. Otherwise the cart modal dialog will not be rendered.

totalPriceStatus

optionalenum

The status of the total price. If it is a variable subscription, the status should be NOT_CURRENTLY_KNOWN.

Default: 'FINAL'

transactionId

optionalstring

Correlation ID to refer to this transaction.

This field is optional. It is generated by the merchant and used to reference this transaction later, such as for debugging issues when communicating with Google.

intent_id

optionalstring

The ID of the Payment Intent you would like to checkout. Required when mode is 'payment'.

layout

optionalHppLayout

The layout of the Hosted Payment Page.

locale

optionalenum

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

logoUrl

optionalstring

The URL of your website logo to display on the header of the Hosted Payment Page.

methods

optionalenum[]

Specify the payment methods and their order for display on the payment page. By default, the order will be based on the order configured in Get available payment method types API, with 'applepay', 'googlepay' and 'paypal' displayed at the top if they're supported. Note: Only payment methods supported for the specified currency and country_code will be shown on the payment page.

mode

optional'payment' | 'recurring'

The checkout mode for the shopper.

Default: 'payment'

payment_consent

optionalPaymentConsentOptions

The payment consent details.

platformConnectedAccount

optionalstring

When using Payments for Platforms, specify the ID of the connected account associated with the payment if you want to use its information to process the payment. For example, the statement descriptor displayed on the shopper's credit card or bank statement and the payment methods activated by the connected account.

recurringOptions

optionalRecurringOptions

Options for recurring flow.

requiredBillingContactFields

optional('name' | 'email' | 'country_code' | 'address' | 'phone')[]

The billing information that you require from the user in order to process the transaction.

savedPaymentMethod

optionalSavedPaymentMethodOptions

The options for saved payment method.

Default: { displayMode: 'auto', saveMode: 'auto' }

shopper_email

optionalstring

The shopper's email address.

shopper_name

optionalstring

The shopper's full name.

shopper_phone

optionalstring

The shopper's phone number.

showTermLink

optionalboolean

submitType

optional'pay' | 'book' | 'subscribe' | 'save'

Describes the type of transaction being performed in order to customize the submit button text. Available options are 'pay', 'book', 'subscribe', 'save'. If blank, the default value will be 'pay'

Default: 'pay'

successUrl

optionalstring

The HTTPS URL to redirect shoppers when payment is successful.

wechatpay

optionalWeChatPayFlow

The options for WeChat Pay.

components

optionalenum[]Deprecated

The payment methods your website would like to integrate with.

use methods instead

failUrl

optionalstringDeprecated

The HTTPS URL to redirect shoppers when payment fails. We do not recommend merchants to pass this value. If a payment fails, shoppers should retry the payment or switch to a different payment method instead of redirecting to a failure URL.

theme

optionalHppThemeDeprecated

use appearance instead

withBilling

optionalbooleanDeprecated

Used to increase the likelihood of 3DS frictionless checkout. Set this to true if you want the payment form to collect billing information from the shopper. Only applies to card payment method.

please use requiredBillingContactFields instead

Returns

void | string

redirectToCheckout(props)

1import { init } from '@airwallex/components-sdk';
2
3const { payments } = await init({
4  env: 'demo', // Choose the Airwallex environment ('demo' or 'prod')
5  enabledElements: ['payments'],
6});
7payments.redirectToCheckout({
8  intent_id: 'replace-with-your-intent-id',
9  client_secret: 'replace-with-your-client-secret',
10  currency: 'replace-with-your-currency',
11  country_code: 'replace-with-your-country-code',
12});

Was this page helpful?