Accept Payments with the Airwallex Gateway (Beta)
Selling in many currencies often means a card processor that converts every sale. If you already hold those currencies in Airwallex, you may want checkout payments to land there too.
Stackless for FluentCart adds Airwallex to FluentCart → Settings → Payments as Airwallex Beta (Stackless), with your own API key. Buyers pay on Airwallex’s hosted checkout by card or local method, saved cards renew subscriptions, and refunds and disputes come back into FluentCart. You stay the seller, so tax stays yours.
This gateway is in beta. It uses Airwallex’s Checkout Session API, which Airwallex has in beta. It was tested against a simulated Airwallex API and hasn’t taken a sandbox or real payment, so run a test payment before you take live ones.
Before You Start
- FluentCart 1.6.4 or newer.
- An Airwallex account that can use Checkout Sessions. Ask Airwallex if you aren’t sure.
- A separate Airwallex sandbox account for test orders.
- Automatic Currency Conversion turned off in Airwallex. A payment in another amount or currency doesn’t complete its order.
- A public HTTPS site for webhooks, and working WordPress scheduled tasks for renewals and payment checks.
Turn On the Gateway
- Go to FluentCart → Stackless and switch on Payment Gateways on the Stackless Dashboard. The switch saves at once.
- Open Settings on the Payment Gateways card, make sure Airwallex (beta) is ticked under Gateways to add to FluentCart and click Save changes. Clearing it later takes it off checkout and keeps its settings saved.
- Open FluentCart → Settings → Payments and choose Manage on Airwallex Beta (Stackless).
Buyers see it as Airwallex.
Create the API Key
- In Airwallex, open Settings → Developer → API keys and create a key with these permissions: Payment Acceptance (write), Checkout Sessions (write) and Payment Disputes (read).
- Copy the client ID and API key. The account ID is under Settings → Account details.
- Paste all three into Client ID, API key and Account ID, on the Live credentials or Sandbox credentials tab.
- Leave API key covers on Only this account, or choose Several accounts if the key covers more than one.
Add the webhook next. The gateway won’t save as active without its secret.
Connect the Webhook
Stackless doesn’t create this webhook. Add one for live and one for sandbox, following Airwallex’s webhook guide:
- In the Airwallex web app, open Developer → Webhooks, click New webhook and enter the URL below.
- Set its API version to
2026-08-21. - Select the events listed below.
- Copy its secret into Webhook secret on the matching tab.
- Turn on Payment Activation and save. A working connection says “Airwallex connected.”
https://yoursite.com/?fluent-cart=fct_payment_listener_ipn&method=gtfc_airwallex
- Checkout
checkout_session.completedcheckout_session.cancelled
- Payments
payment_intent.succeededpayment_intent.pendingpayment_intent.pending_reviewpayment_intent.payment_failedpayment_intent.cancelled
- Saved cards
payment_consent.disabled
- Refunds
refund.receivedrefund.acceptedrefund.settledrefund.failed
- Disputes
payment_dispute.requires_responsepayment_dispute.challengedpayment_dispute.acceptedpayment_dispute.expiredpayment_dispute.pending_closurepayment_dispute.pending_decisionpayment_dispute.wonpayment_dispute.lostpayment_dispute.reversed
Unsigned or badly signed events are refused, and each event is applied once. Stackless reads the payment, refund or dispute from Airwallex before it changes an order, and ignores payments other sites took on the same account.
The API key and webhook secret are stored encrypted. To keep credentials out of the database, define them in wp-config.php. A defined value hides its field:
define('GTFC_AIRWALLEX_LIVE_CLIENT_ID', '...');
define('GTFC_AIRWALLEX_LIVE_API_KEY', '...');
define('GTFC_AIRWALLEX_LIVE_ACCOUNT_ID', '...');
define('GTFC_AIRWALLEX_LIVE_WEBHOOK_SECRET', '...');
define('GTFC_AIRWALLEX_TEST_CLIENT_ID', '...');
define('GTFC_AIRWALLEX_TEST_API_KEY', '...');
define('GTFC_AIRWALLEX_TEST_ACCOUNT_ID', '...');
define('GTFC_AIRWALLEX_TEST_WEBHOOK_SECRET', '...');
Run a Test Payment
Test order mode covers the whole store: buyers can’t pay with real cards and renewals of live subscriptions wait, so pick a quiet time or use a separate test site. Refunds and renewal charges only run on a site Stackless treats as the live store. Staging Copies explains how that’s decided.
- Put FluentCart in Test order mode, with the sandbox credentials and webhook secret saved.
- Place a one-time order and check that it turns paid.
- Refund it from FluentCart. Pay another order, refund that one in Airwallex and check that the refund appears on the order.
- If you sell subscriptions, start one on a daily plan and check that the next day’s renewal charges the saved card.
- Switch to Live order mode, then make one small real payment and refund it.
What Buyers See
- Checkout says “After you place the order you pay on Airwallex’s secure page, then come back here.”
- A payment that saves no card offers the methods Airwallex shows for your account and that currency. A payment that saves a card offers cards only.
- When nothing is due today on an auto-charged subscription, the buyer ticks a box agreeing to save the card.
- Back on your site, Stackless reads the payment from Airwallex before it marks the order paid. Slower methods, such as transfers and vouchers, stay pending until the money arrives.
- Placing the same order again reuses the open checkout. If an earlier payment might still go through, the buyer is asked to wait.
Subscriptions and Renewals
FluentCart schedules every renewal and works out its amount. No subscription is created at Airwallex. What buyers get depends on Renewal Billing, in the Subscriptions section of FluentCart’s store settings. A change there affects new subscriptions only:
| Renewal Billing | Subscriptions paid with Airwallex |
|---|---|
| Store Billing with Auto-charge saved payment methods | The first payment saves the card and FluentCart charges it on each renewal. A free trial saves the card without charging it. |
| Store Billing without auto-charge | No card is saved, and the customer pays each renewal by link. Not offered when nothing is due today. |
| Gateway Billing with Allow all payment methods (Manual Fallback) | No card is saved, and the customer pays each renewal by link. Not offered when nothing is due today. |
| Gateway Billing without it | Airwallex isn’t offered for new subscriptions. |
- Only cards renew. If a paid first order saves no card, the subscription moves to renewals paid by link. A free trial doesn’t start until a card is saved.
- A renewal the bank wants approved is emailed to the customer to pay.
- A charge without a clear answer stays processing and is checked again. No second charge starts until the first is settled.
- When Airwallex disables a saved card’s consent, the
payment_consent.disabledevent removes that card. - Cancel in FluentCart. There’s no schedule to cancel at Airwallex.
- Saved cards belong to the connected account ID. If you connect another account, they can’t be charged.
Refunds and Disputes
- Full and partial refunds from FluentCart go to Airwallex.
- Refunds made in Airwallex are recorded on the order once, by webhook.
- If Airwallex doesn’t confirm a refund, refund the same amount again and don’t refund another way. It isn’t sent twice.
- A refund that fails after it was recorded adds an order note saying the customer didn’t get the money.
- A chargeback puts a processing or completed order on hold once. A request for information and any later news only add notes. Respond in Airwallex, and change the order’s status yourself when it’s over.
Payments That May Need a Refund
A payment the order wasn’t waiting for never completes it. Examples are a second payment, one for another amount, one that arrives after the buyer switched payment method, or one refunded before your store confirmed it.
- It’s logged on the order and listed in the admin notice Payments that may need a refund, with its payment ID.
- An unpaid order goes on hold, and no new Airwallex payment or saved-card charge starts for it while the payment is listed.
- Refund it in Airwallex. The notice clears when webhooks report refunds for the whole amount. You can also click Mark as handled. Either way, that payment never pays the order, and the order’s status stays as it is.
- A renewal with such a payment isn’t charged to the saved card again automatically, even after you clear it. The customer can pay it by link.
Currencies
- Stackless allows 131 of the currencies Airwallex collects. What your account takes is up to Airwallex.
- Currencies with three decimals aren’t offered: BHD, JOD, KWD, LYD, OMR and TND.
- Currencies without decimals, such as JPY and KRW, are rounded to whole units.
With Multi-Currency Checkout, tick Airwallex under Payment gateway routing in each currency that has a saved gateway list. INR, USD, EUR and GBP start with a fixed gateway list that doesn’t include it.
What Data Is Sent
- With each payment: your account ID, the amount, currency, order number, a reference that holds the order ID, return addresses on your site and the site’s language.
- When no card is saved: the buyer’s name, email and billing country.
- When a card is saved: an Airwallex customer is created with the buyer’s name and email. Renewals send that customer’s and card’s references.
- With a refund: the amount, the payment’s ID and the reason you typed, or the order number when you typed none.
- With API requests: your credentials or an access token made from them, and the plugin’s name and version.
- Kept on your site: Airwallex’s references and, for saved cards, the brand, last four digits and expiry. Card numbers go straight to Airwallex.
Limits
- It’s a beta on a beta API and hasn’t taken a sandbox or real payment. Test a payment, a refund and a renewal on your own account first.
- The webhook has to be added by hand in each environment.
- Airwallex can’t be duplicated for a second account.
- A subscription another provider bills on its own schedule can’t be moved to Airwallex by paying with it.
- A subscription that a recurring coupon makes free doesn’t show Airwallex at checkout.
- There’s no page for customers to change a saved card. When they pay an auto-charged renewal by link, that card replaces the saved one.
- On copies of the live store, saved cards aren’t charged and refunds aren’t sent. A shopper who checks out on a copy that has live keys is still charged, so use test mode there.
For Developers
| Hook | Type | Use |
|---|---|---|
gtfc/airwallex/settings | filter | The gateway’s settings when they load: ($settings). |