Search...
APIJSLog inGet started in sandbox
Airwallex logo
Home
Platform APIs
Connected Accounts
Accounts
Payments
Billing
Transactional FX
Payouts
Issuing
Embedded Finance Use Cases
Global Treasury
Banking as a Service
Payments for Platforms
Developer Tools
Trust Center
Help Center
API Reference
Back to home
OverviewHow Airwallex Billing worksGet started with billingChoose your billing solutionConfigure your billing settingsSupported currencies
Invoicing
Subscriptions
Get started with subscription managementSubscriptions via API
Sample integration
Billing components
Test and go live

Sample integration

This guide shows you how to build a subscription flow for a SaaS service with multiple flat‑rate plans.

At a high-level, the steps include:

  1. Model products and define multiple flat‑rate plans.
  2. Create a checkout for subscription plans.
  3. Handle billing events with webhooks.
  4. Test and troubleshoot the subscription lifecycle.

Upon completion of these steps, customers will be able to select a plan, complete checkout, and manage their recurring payments. You will set up backend and frontend logic to create subscriptions, process billing events, and support customer self‑service.

Example business scenario

Imagine a project management SaaS web application that provides two subscription plans:

  • Basic: $10/month, includes core features.
  • Pro: $20/month, includes advanced features.

Both plans have a fixed monthly fee, regardless of usage, and each comes with a 14‑day free trial so customers can explore the service before subscribing. This setup is known as a flat‑price subscription model.

Other billing models you may encounter include:

  • Tiered pricing: Different rates apply when usage exceeds specified thresholds.
  • Usage‑based billing: Charges based on units consumed, such as API calls or storage.

For this guide, we’ll use flat pricing with multiple plans because it is the most straightforward and commonly used structure for SaaS integrations.

Before you begin

Before you begin, ensure your SaaS application includes both a frontend (web client) and a backend (server), as these components must work together during integration. You will also need:

  • An Airwallex account (sandbox environment is recommended).
  • Your API key and client secret, available from the Airwallex web app.

Step 1: Create products and prices

A Product represents what you sell. A Price specifies the billing interval, currency, and amount. For each subscription plan, follow these steps:

  • Create a Product object for each plan (for example, Basic, Pro).
  • Create a corresponding Price object for each product, defining the monthly charge (for example, $10/month for Basic, $20/month for Pro).

You can set up Products and Prices in two ways:

  • Airwallex web app (ideal if you prefer a UI-driven workflow)

    • Log in to your Airwallex web application.
    • Go to Products & Prices.
    • Create a new Product (for example, Basic Plan).
    • Add a Price to the Product, specifying the currency, amount, and billing interval.

  • Airwallex Billing APIs

To integrate via API, start by creating a Product API that represents your subscription plan (for example, Basic). The API response will return an id that uniquely identifies the Product object.

Shell

The second API call creates a Price, specifying the amount to charge and the billing frequency. To associate the price with its product, you must provide the id returned from the product creation API call.

Shell

Step 2: Build a checkout

Enable customers to subscribe using Hosted Billing Checkout.

HTML (app.html)

  1. Build a simple HTML page displaying two subscription plans — Basic and Pro — and a form to collect the user's email address.
  2. Present each plan with its price and a subscribe button.
  3. Attach a unique request_id to each subscribe button. This allows your backend to recognize repeated requests as the same operation, ensuring idempotency.
  4. This HTML integrates with the JavaScript code you'll add next: when a button is clicked, the JS logic will capture the email and selected plan, send a request (including the request_id) to your backend, and redirect the user to Checkout if the request succeeds.

To improve the user experience and prevent duplicate requests, consider disabling the subscribe button while the request is being processed in a production environment.

HTML

JavaScript (app.js)

This script enables subscription buttons on your HTML page by performing several key functions:

  • It captures the customer’s email address along with their selected plan.
  • It leverages the unique request_id attached to each button to ensure idempotency, preventing duplicate subscriptions if a request is retried.
  • It sends all necessary details to your backend endpoint Create a Billing Checkout API.
  • Redirects the user to the Airwallex hosted billing checkout page if everything succeeds.
Javascript

This backend code processes requests from your frontend to initiate creation of a Airwallex Billing Checkout object. It performs the following actions:

  • Receives the email, priceId, and requestId from the request body.
  • Calls the Airwallex Billing Checkout API to create a Billing Checkout object.
  • Sets a 14-day trial period using the trial_ends_at timestamp.
  • Implements idempotency using the request_id to prevent duplicate sessions from repeated requests.
  • Returns the Checkout URL back to the frontend, allowing the customer to complete their subscription.
JavaScript

Step 3: Handle webhook events

Airwallex notifies your system about billing events. Set up a webhook endpoint to manage subscription lifecycle changes as follows:

  • Receive event notifications: Airwallex sends JSON payloads to your webhook URL whenever a key event occurs, such as a payment succeeding or failing.
  • Parse the event type: Inspect the event.type field in the payload to identify the specific event.
  • Take appropriate action: For example, provision access for new subscriptions, continue service after successful payments, or alert the customer when a payment fails.
  • Acknowledge receipt: Return a 200 OK response so Airwallex knows your system successfully processed the event.

See Billing event types for webhooks emitted for subscriptions.

Example

node.js

Step 4: Test your integration

Use Airwallex sandbox test card numbers to simulate checkout flows. To test longer subscription cycles, use the Test Clock feature (coming soon) to fast-forward time, making it easy to test renewals, trial expirations, and cancellations without real-time delays.

Verify your setup by checking the following:

  • Dashboard visibility: After checkout, new subscriptions should appear in your dashboard on the Airwallex web app.
  • Webhook events: Ensure webhook events are triggered and processed successfully by your application.
  • Customer Portal: Any customer changes including updating cards, switching plans, or cancellation should be reflected both in the portal and your backend system.
  • Test clock usage: Accelerate subscription cycles with the test clock, allowing you to quickly test renewals, trial expirations, and cancellations.
Was this page helpful?
On this page
Was this page helpful?