> ## Documentation Index
> Fetch the complete documentation index at: https://funnelfox.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Airwallex integration
> Connect Airwallex to FunnelFox Payments through Primer, set up webhooks, 3DS, and device fingerprinting.
Airwallex is one of the PSPs
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](/docs/billing/payments-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.
3. Click **Connect** under **Airwallex**.
4. Keep Primer open and go to your Airwallex account in another browser tab.
5. Go to **Settings > Developer > API keys** in Airwallex.
6. Click **New scoped API key** at the top right.
7. Name your key and configure its scope. It needs the **Payment Acceptance**
and **Payment Disputes** scopes.
8. 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.
9. Go back to Primer and paste the key into **API key**.
10. Go back to Airwallex and copy the **Client ID** for the key you created.
11. Go back to Primer and paste the ID into **Client ID**.
12. 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.
3. Name your webhook.
4. Go back to the Airwallex integration in Primer and copy the endpoint URL
under **Set up webhook**.
5. Go back to Airwallex and paste the URL into **Notification URL**.
6. Go to **Payment events** under the **Events** section and enable
`Refund.Failed`, `Refund.Accepted`, and all **Payment Dispute** events.
7. Click **Create**.
8. 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**.
2. Name your webhook.
3. Paste your FunnelFox Payments webhook endpoint into **Notification URL**:
```
https://billing.funnelfox.com/{org_id}/v1/airwallex/webhook
```
Replace `{org_id}` with your organization ID, which looks like
`live_xxxx000000`. The result looks like this:
```
https://billing.funnelfox.com/live_af123456bb789/v1/airwallex/webhook
```
4. Go to **Payment events** under the **Events** section and enable
`Refund.Accepted` and `payment_attempt.capture_requested`.
5. Click **Create**.
6. Open the webhook you just created and copy its **Secret key**.
7. 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](/docs/billing/payments-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**.
3. Complete the form:
* **Primer Organisation ID**: Find it in the
[Primer Dashboard](https://dashboard.primer.io/settings/organisation) under
**Settings > Organisation**.
* **Processor (PSP)**: Select Airwallex.
* **Merchant Account**: Find it in the
[Primer Dashboard](https://dashboard.primer.io/integrations) 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.
4. Click **Submit request**.
### 5. Pass device data
This step applies only if you build your checkout with the
[FunnelFox Payments Web SDK](/docs/billing/integration-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:
```json theme={null}
{
"ipAddress": "1.2.3.4",
"deviceId": "device_123"
}
```
### 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
* [Recover failed payments automatically](/docs/billing/payments-retries)
* [Manage payments and process refunds](/docs/billing/payments-management)
* [Secure payment data with tokenization](/docs/billing/payments-tokenization)