Setting up Airwallex

A click-by-click walkthrough for connecting your own Airwallex account, testing it, and going live. No technical knowledge needed.

Time: about 30 minutes, plus however long Airwallex takes to verify your business (usually a few days).

You will move between two browser tabs: your Airwallex account and your workspace's back office. Keep both open.

Before you start

Have these to hand:

• An Airwallex business account, or the details to open one: your company registration, the people who own and run it, and ID
• Your plans already created under What you sell → Plans & pricing

Airwallex suits businesses selling in Asia-Pacific — especially Singapore — and adds local methods such as PayNow and GrabPay. It does not collect or pay sales tax, VAT or GST for you: if you are registered for tax, include it in your plan prices.

Step 1 — Open your account, and a sandbox

1. Sign up at airwallex.com and complete the business verification.
2. Ask Airwallex for a sandbox account as well — a practice copy with pretend money. You can request one from the developer section of your account, or through Airwallex support.
3. Make sure Billing (subscriptions and invoices) is switched on for your account. If you are not sure, ask Airwallex support to turn it on — checkout for monthly and yearly plans needs it.

Do steps 2 to 7 in the sandbox first.

Step 2 — Copy your Client ID and API key

1. In Airwallex, open Settings → Developer → API keys.
2. Copy the Client ID.
3. Create an API key and copy it straight away — Airwallex may only show it once.

Treat the API key like a password.

Step 3 — Paste them into your workspace

1. In your workspace, open Setup → Payments, find the Airwallex card and click Set up.
2. Set Environment to Test.
3. Paste the Client ID and API key.
4. Tick Take payments through Airwallex.
5. Click Save, then Test connection.

The Status card should say Verified. If it says Failed, the message underneath tells you why.

Step 4 — Connect the webhook

The webhook is how Airwallex tells your workspace that somebody has paid. Without it, customers are charged and get nothing. Do not skip this step.

1. On your workspace's Airwallex page, find Webhook endpoint and click the copy button. It is private to you — treat it like a password.
2. In Airwallex, open Settings → Developer → Webhooks and add a webhook.
3. Paste the address as the URL.
4. Set its API version to the one shown on your workspace's Airwallex page. This matters: Airwallex names its events differently between versions.
5. Tick each of these events:
   • invoice.payment.paid
   • subscription.active
   • subscription.in_trial
   • subscription.modified
   • subscription.unpaid
   • subscription.cancelled
   • refund.accepted
   • refund.settled
6. Save, then copy the webhook's secret.
7. In your workspace, paste it into Webhook secret and click Save.

Step 5 — Turn Airwallex on for your customers

Open Setup → Payments and click Use Airwallex on its card.

Nothing to set up for your plans. The first time somebody buys a plan, it is created in your Airwallex account automatically.

Local payment methods such as PayNow and GrabPay are switched on in Airwallex, in your payment settings. They are offered for lifetime plans and credit packs; monthly and yearly plans are paid by card or wallet, because they renew automatically.

Step 6 — Make a test purchase

1. Open your website in a private (incognito) window and register as a customer, using a different email from your own login.
2. Choose a paid plan and click Pay. You are taken to Airwallex's checkout.
3. Pay with one of the test cards from Airwallex's testing guide (search their documentation for "test card numbers").
4. You are brought back to your billing page. Within a minute the plan and credits appear.
5. In your back office, Your customers → Payments shows the payment.

Then try cancelling from the customer's billing page, and refunding from Payments. Airwallex confirms refunds, so the payment shows Refund pending for a moment first.

Step 7 — Go live

1. In your live Airwallex account, repeat steps 2 and 4. Live has its own Client ID, API key, webhook and secret.
2. In your workspace's Airwallex page, set Environment to Live, paste the live credentials and secret, click Save and Test connection.
3. Make one small real purchase yourself, then refund it.

Moving from Test to Live sets your plans up again in the live account automatically. You are live.

If you get stuck

"Failed" after Test connection. The Client ID or API key is wrong, or comes from the other account — sandbox keys only work with Test, live keys only with Live.

Paid in Airwallex, nothing here. The webhook: the address must be exactly the one shown on your workspace's page, the API version must match, every event ticked, and the secret pasted in.

Monthly or yearly plans cannot be bought. Billing is not switched on for your Airwallex account. Ask Airwallex support to enable it.

Back to: Payments · Next: Vouchers