Skip to main content
Airwallex is one of the you can connect to FunnelFox Payments, alongside the others already in your payment stack. You connect it through Primer, which routes your payments to Airwallex as part of your payment orchestration setup.

​
Setup

You need admin access to both your Airwallex account and your Primer account. Keep both open in separate browser tabs, because the setup moves back and forth between them.

​
1. Connect Airwallex to Primer

  1. Go to Integrations in your Primer dashboard.
  2. Click New integration at the top right.
  1. Click Connect under Airwallex.
  1. Keep Primer open and go to your Airwallex account in another browser tab.
  2. Go to Settings > Developer > API keys in Airwallex.
  3. Click New scoped API key at the top right.
  1. Name your key and configure its scope. It needs the Payment Acceptance and Payment Disputes scopes.
  2. Click Create to generate the key, then copy it.
    Copy the API key now. Airwallex shows it once, and you cannot retrieve it later. If you lose it, create a new key.
  3. Go back to Primer and paste the key into API key.
  1. Go back to Airwallex and copy the Client ID for the key you created.
  1. Go back to Primer and paste the ID into Client ID.
  1. Click Connect.

​
2. Set up Primer webhook in Airwallex

This webhook tells Primer about refunds and disputes that happen in Airwallex.
  1. Go to Settings > Developer > Webhooks in Airwallex.
  2. Click New webhook at the top right.
  1. Name your webhook.
  2. Go back to the Airwallex integration in Primer and copy the endpoint URL under Set up webhook.
  1. Go back to Airwallex and paste the URL into Notification URL.
  1. Go to Payment events under the Events section and enable Refund.Failed, Refund.Accepted, and all Payment Dispute events.
  1. Click Create.
  2. Click Finish in the Airwallex integration in Primer.

​
3. Set up FunnelFox Payments webhook in Airwallex

Airwallex needs a second webhook that posts refund and capture events straight to FunnelFox Payments.
  1. Go back to Settings > Developer > Webhooks in Airwallex and click New webhook.
  1. Name your webhook.
  2. Paste your FunnelFox Payments webhook endpoint into Notification URL:
    Replace {org_id} with your organization ID, which looks like live_xxxx000000. The result looks like this:
  3. Go to Payment events under the Events section and enable Refund.Accepted and payment_attempt.capture_requested.
  1. Click Create.
  2. Open the webhook you just created and copy its Secret key.
  1. Go to the Settings page of your FunnelFox Payments dashboard, paste the key into Airwallex webhook secret, and press Enter.

​
4. Set up 3DS

Adaptive 3DS applies authentication only when a payment needs it. Airwallex needs its own 3DS profile. First, collect these values from Airwallex:
  • Acquirer BIN: One per card network (Visa, Mastercard, AMEX, UnionPay).
  • MID: One per card network.
  • Merchant name
  • Merchant URL
  • Merchant country code: ISO 3166-1 alpha-2, for example US.
  • Merchant Category Code (MCC)
Then request the profile from your FunnelFox Payments dashboard:
  1. Go to the Payment Features page.
  2. Click Request to the right of Adaptive 3DS.
  1. Complete the form:
    • Primer Organisation ID: Find it in the Primer Dashboard under Settings > Organisation.
    • Processor (PSP): Select Airwallex.
    • Merchant Account: Find it in the Primer Dashboard under Integrations > Airwallex > Merchant Account.
    • Display name: Name for the 3DS profile.
    • Merchant name: Name shown in the authentication window.
    • Merchant URL: A bare domain like example.com is fine.
    • Country code: ISO 3166-1 alpha-2, for example US.
    • Merchant Category Code (MCC): Exactly 4 digits, for example 5734.
    • Card networks: Select at least one (Visa and Mastercard are selected by default). For each selected network, enter:
      • Processor Merchant Account ID (MID)
      • Acquirer BIN
Optionally, send your Airwallex legal entity name and legal entity ID to your Solutions manager at FunnelFox. It speeds up verification on the Airwallex side.
  1. Click Submit request.

​
5. Pass device data

This step applies only if you build your checkout with the FunnelFox Payments Web SDK. If you use FunnelFox funnels, skip to the next step.
Airwallex needs the customer’s IP address and device identifier for its fraud risk assessment. Pass both in the metadata field of your createClientSession request:

​
6. Turn on device fingerprinting

  1. Go to the Settings page of your FunnelFox Payments dashboard.
  2. Set Airwallex device fingerprinting for fraud risk assessment to Yes, then press Enter.
Your Airwallex integration is now complete. Primer can route payments to Airwallex, and Airwallex reports refunds and disputes back to Primer and FunnelFox Payments.

​
Next steps