Skip to content

Payments

GatewayStatusFeatures
AirwallexProduction (primary)Cards, WeChat Pay, Alipay, 3DS
StripeProduction (legacy)Cards, Apple Pay, Google Pay, 3DS
MockTestingSimulates success/failure
[payment]
default_gateway = "airwallex" # or "stripe" / "mock"
[payment.airwallex]
enabled = true
client_id = "..." # Airwallex dashboard → API keys
api_key = "..." # Airwallex dashboard → API keys
webhook_secret = "..." # verify webhook signatures
demo = true # true = sandbox, false = production
[payment.stripe]
enabled = true
secret_key = "sk_..."
publishable_key = "pk_..."
  1. POST /checkout/complete — creates order + payment intent, returns client_secret / payment_intent_id and an airwallex_env hint
  2. Client-side: mount the Airwallex Drop-in (or Stripe Elements) with client_secret
  3. Customer enters payment details and confirms
  4. POST /checkout/confirm — server verifies payment and finalizes order

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 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 }
});
Terminal window
POST /api/v1/payments/:id/refund
{ "amount": 50.00, "reason": "Customer request" }

Partial refunds supported. The refund is processed through the original gateway.

Payment status changes trigger webhooks:

  • payment.succeeded — payment confirmed
  • payment.failed — payment declined
  • refund.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.