Payments
Supported gateways
Section titled “Supported gateways”| Gateway | Status | Features |
|---|---|---|
| Airwallex | Production (primary) | Cards, WeChat Pay, Alipay, 3DS |
| Stripe | Production (legacy) | Cards, Apple Pay, Google Pay, 3DS |
| Mock | Testing | Simulates success/failure |
Configuration
Section titled “Configuration”[payment]default_gateway = "airwallex" # or "stripe" / "mock"
[payment.airwallex]enabled = trueclient_id = "..." # Airwallex dashboard → API keysapi_key = "..." # Airwallex dashboard → API keyswebhook_secret = "..." # verify webhook signaturesdemo = true # true = sandbox, false = production
[payment.stripe]enabled = truesecret_key = "sk_..."publishable_key = "pk_..."Checkout flow
Section titled “Checkout flow”POST /checkout/complete— creates order + payment intent, returnsclient_secret/payment_intent_idand anairwallex_envhint- Client-side: mount the Airwallex Drop-in (or Stripe Elements) with
client_secret - Customer enters payment details and confirms
POST /checkout/confirm— server verifies payment and finalizes order
Airwallex
Section titled “Airwallex”Airwallex is the primary production gateway. It authenticates with a
client ID + API key pair, and its demo/prod API base is selected by the
demo config flag (or the AIRWALLEX_USE_DEMO=1 env var).
The checkout summary’s airwallex_env always tells the client which
environment the intent was created in — the storefront’s build-time
PUBLIC_AIRWALLEX_ENV is only a fallback for when the server does not
report one. Keep them in agreement (set PUBLIC_AIRWALLEX_ENV=prod when
the backend stops running in demo mode).
Load the Drop-in SDK from CDN:
<script src="https://static.airwallex.com/components/sdk/v1/index.js"></script>await AirwallexComponentsSDK.init({ env: summary.airwallex_env, // 'demo' or 'prod' enabledElements: ['payments'],});const dropIn = await AirwallexComponentsSDK.createElement('dropIn', { client_secret: result.client_secret, currency: 'USD', intent_id: result.payment_intent_id,});dropIn.mount('airwallex-drop-in');dropIn.on('success', () => { /* POST /checkout/confirm */ });Settlements: Airwallex settles charges in batches. Fees, settlement batch
IDs, and FX rates are backfilled onto payments with
POST /api/v1/accounting/sync-settlements — see the
Accounting Export reference.
Stripe (legacy)
Section titled “Stripe (legacy)”Stripe Elements integration remains available. The client_secret from
checkout complete is passed to Stripe.js on the client.
const stripe = await loadStripe(publishableKey);const { error } = await stripe.confirmCardPayment(clientSecret, { payment_method: { card: cardElement }});Refunds
Section titled “Refunds”POST /api/v1/payments/:id/refund{ "amount": 50.00, "reason": "Customer request" }Partial refunds supported. The refund is processed through the original gateway.
Webhooks
Section titled “Webhooks”Payment status changes trigger webhooks:
payment.succeeded— payment confirmedpayment.failed— payment declinedrefund.succeeded— refund processed
Configure webhook endpoints in the admin or via API. For Airwallex, set the
webhook secret in [payment.airwallex] so signatures can be verified.