Airwallex Hosted Payments — setup and reference

Module and release scope

This guide covers Airwallex Hosted Payments 1.0.3, Extension API 1, from the reviewed product source. Its declared core range is 1.3.5–1.3.99. Use the matching released core and signed provider package; a version label alone does not install the required contracts. Source availability does not mean the module is bundled in every currently downloadable product, installed on your server, enabled or certified for your merchant/server account. Nothing in this guide enables a provider or changes your existing connections.

Open System → Payment gateways (newer source may group these as Payments, Domain services or Hosting services). Install the reviewed signed package through Modules & addons or the integration workspace's Install tab, enable the module separately, add an account/connection, save its own credentials, run its stated Test and explicitly enable the connection. Saving or retesting disables the connection until you enable it again. Start with the provider's test environment where supported; otherwise use an isolated account or server.

Exact connection fields

These are the fields declared by this module. Secret values are entered privately and encrypted by the application. Defaults are configuration hints, not approved live merchant settings. Internal fields are populated by the module and are not operator-editable.

This payment module creates one Airwallex PaymentIntent for an issued invoice and redirects its owner to the Airwallex hosted payment page. Card and wallet details are collected by Airwallex. The application never accepts card numbers or CVCs. Each invoice is paid separately; this release does not store cards, charge renewals automatically, refund payments, create provider invoices, or initiate currency conversion.

Configuration

Install the accompanying core update before enabling this package: it provides HostedCheckoutBridge, ConnectionCurrencySupport, the authenticated /account/payments/{attempt}/hosted bridge, and the extended verified-payment binding.

In System → Payment gateways, create an Airwallex connection. Choose Sandbox or Live, then enter the corresponding Client ID, API key, payment account ID, webhook signing secret and enabled invoice currencies. Use a separate connection and secret for each environment or merchant account. No credentials are included in the package.

The optional Card statement descriptor field requests the text shown on a customer's card statement for new payments. Enter up to 32 characters without control characters or line breaks. Leading and trailing spaces are removed; the remaining wording is sent exactly as configured. Leave it blank to omit Airwallex's descriptor API field and use the registered business name. Airwallex may need to enable custom descriptors for the merchant account, and the issuing bank controls the final statement display. The read-only connection test validates the local value, but does not verify descriptor acceptance. Changes affect newly created PaymentIntents; existing intents and completed payments retain their original descriptor. No descriptor is sent when retrieving, reconciling or verifying an existing payment.

The currency field accepts USD, AUD, PKR and SAR. These are supported presentment currencies in Airwallex's published reference and have two decimal places, matching this application's money representation. Enable only currencies approved for the merchant's activated payment methods. Airwallex handles settlement to the merchant separately; the invoice's amount and currency remain unchanged. A currency outside the connection's list is unavailable at checkout.

The API key needs Payment Acceptance write/read access for creating and retrieving PaymentIntents, and Account Capabilities read access. Authentication supplies x-login-as with the configured account ID, so multi-account scoped keys use the intended account. The connection test authenticates and reads Visa and Mastercard capability statuses. At least one must be ENABLED; the test does not submit a payment, enable a capability or create a webhook. An authenticated key alone is insufficient.

Under Airwallex Developer → Webhooks, create a notification endpoint using the callback URL shown on the connection and subscribe to payment_intent.succeeded. Copy its actual signing secret into the connection. Configure matching sandbox/live accounts. Finish a sandbox hosted-checkout payment and webhook delivery test before enabling live customer payments; the read-only connection test does not prove webhook delivery or merchant-specific currency acceptance.

Payment and verification

request_id and merchant_order_id both use the reserved checkout attempt UUID. This preserves Airwallex create idempotency for that attempt. Trusted metadata binds the attempt, immutable invoice public ID, connection, merchant account, environment, integer amount and currency. Existing core reservations prevent a second simultaneous gateway or offline payment for that invoice.

The module returns an authenticated application bridge URL. The bridge reads the same provider intent and releases its temporary client_secret only to the authorized invoice owner. It creates no replacement intent. The token expires after 60 minutes; expired or uncertain attempts require reconciliation before a new payment. Neither API keys nor authentication access tokens are sent to the browser.

The bridge uses the current official Airwallex.js hosted-payment-page integration:

<script src="https://static.airwallex.com/components/sdk/v1/index.js"></script>

const { payments } = await window.AirwallexComponentsSDK.init({
  env: environment, // "demo" for Sandbox, "prod" for Live
  enabledElements: ["payments"],
});
await payments.redirectToCheckout({
  env: environment,
  mode: "payment",
  currency,
  intent_id,
  client_secret,
  successUrl: return_url,
});

The browser return is navigation only. It never marks the invoice paid. The signed webhook requires a single x-timestamp (milliseconds) and x-signature, authenticates HMAC-SHA256 over timestamp plus the original request body, enforces a five-minute delivery tolerance, and rejects a different account. Both documented account field variants (account_id and accountId) are accepted; every supplied value must match the configured account. It retrieves the PaymentIntent again through the account-scoped API. Only SUCCEEDED with the full matching captured_amount is accepted. Authorization, risk review, pending states and partial capture do not allocate payment. The core verifies invoice/attempt/connection/currency/amount/intent binding and records each provider reference idempotently.

Staff reconciliation uses the same authoritative read. A provider-confirmed CANCELLED intent can close unpaid only when its captured amount is zero. REQUIRES_PAYMENT_METHOD is not terminal and cannot release a still payable hosted page.

Provider documentation

• Hosted-payment-page quickstart and current SDK
• PaymentIntent creation, retrieval, statuses and captured amount
• API authentication and account-scoped login
• Available account payment methods
• DropIn eligibility and available methods
• Read-only payment capability verification
• Webhook headers, signature and account identity
• Supported presentment currencies and decimal precision
• PaymentIntent lifecycle and idempotency

Version 1.0.3 adds optional read-only payment method discovery. The matching core update exposes an authenticated invoice preview endpoint; invoice HTML rendering performs no discovery requests. It queries Airwallex Config with the invoice currency, billing country and one-off transaction mode. Only active supported methods receive public labels, and only card networks explicitly returned by the provider are displayed. Discovery creates no PaymentIntent and makes no payment-method changes. The existing DropIn checkout performs final account, browser, domain and payment eligibility checks. Successes are cached for 15 minutes and failures for one minute; a failed preview leaves the normal payment action usable.

Version 1.0.2 adds the optional card statement descriptor. Version 1.0.1's safe HTTP/configuration diagnostics for the native Test action are preserved. Merchant credentials and raw provider response bodies are never displayed.