> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# Airwallex

> Connect Airwallex to Payrails for cards, Apple Pay and Google Pay, covering your API keys and the webhook endpoint.

<picture noZoom>
  ![Airwallex logo](https://assets.payrails.io/img/logos/airwallex/logo-full-bleed.svg)
</picture>

> [!NOTE]
>
> **Who should use this guide**
>
> This guide is intended for merchants who:
>
> * Use **Payrails** as a payment orchestrator
> * Use **Airwallex** for card and wallet processing
> * Have access to the Airwallex web app

***

## Create a Airwallex integration in Payrails

1. Log in to the **Payrails** portal.
2. Go to **Settings** → **Integrations**.
3. Select **Add instance** to create a new integration configuration.
4. Select the **workspaces** where this integration should be available.

> [!NOTE]
>
> **About workspaces**
>
> Workspaces determine where this integration is available. They let you isolate provider setups by region or business line, or share the same configuration across multiple workspaces.

***

## Step 1: Choose the integration type

* Select **Payment**.
* Continue to the next step.

***

## Step 2: Choose the provider

* Select **Airwallex**.
* Continue to the next step.

![A screenshot showing Airwallex selected as the provider.](https://mintcdn.com/payrails-42074109/ZzszXSV8HBVpGKdF/images/docs/airwallex-image-01.png?fit=max\&auto=format\&n=ZzszXSV8HBVpGKdF\&q=85\&s=a1da496f9544c0aa9d00f3449899d78c)

***

## Step 3: Configure your Airwallex integration

> [!TIP]
>
> **What you'll need from Airwallex**
>
> Before you begin, make sure you can log in to the Airwallex web app. You'll create an API key and a webhook endpoint there.

***

### Integration instance name

> An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for different regions, currencies, or business needs. Choose a clear, consistent name, as it is used in routing.

**In Payrails**

* Enter an **Instance name** for your integration, for example `merchant_airwallex`.

![A screenshot showing the integration instance name field.](https://mintcdn.com/payrails-42074109/145W1v58K5wnDMNC/images/docs/orchestration/integrations/shared/integration-instance-name.png?fit=max\&auto=format\&n=145W1v58K5wnDMNC\&q=85\&s=470be58979509680650b0cbf8b5eecc4)

***

### Payment methods

**In Payrails**

* Select **Card**, **Apple Pay**, **Google Pay** or any combination.

![A screenshot showing the Airwallex payment method selection.](https://mintcdn.com/payrails-42074109/ZzszXSV8HBVpGKdF/images/docs/airwallex-image-02.png?fit=max\&auto=format\&n=ZzszXSV8HBVpGKdF\&q=85\&s=bedfa0be7f88304e57b2e07b9c2dedf4)

***

### Credentials

**In Airwallex**

1. Go to **Settings** → **API Keys**.
2. Copy the **Client ID** and **API key**. You can create a restricted API key with access to payments.

**In Payrails**

| Field | Value |
| :- | :- |
| **Client ID** | Your Airwallex client ID |
| **API Key** | Your Airwallex API key |
| **Webhook Secret Key** | The secret key of your Airwallex webhook endpoint. Payrails uses it to verify notifications from Airwallex. Fill it in after you create the webhook in the next section. |

Payrails sends requests to the Airwallex demo environment in test mode and to the live environment in live mode, so use the keys for the matching environment.

![A screenshot showing the Airwallex credential fields.](https://mintcdn.com/payrails-42074109/ZzszXSV8HBVpGKdF/images/docs/airwallex-image-03.png?fit=max\&auto=format\&n=ZzszXSV8HBVpGKdF\&q=85\&s=b373265f5afa364b3b0ada4eee777ee0)

***

### Webhooks or notifications

> [!NOTE]
>
> Payrails uses provider webhooks or notifications to receive asynchronous
> payment status updates.

> [!WARNING]
>
> Create webhooks in the same mode (test or live) as your Payrails integration.

**In Payrails**

* Copy the **Notification URL** shown under **Account configuration** at the top of the integration form.

**In Airwallex**

1. Go to **Settings** → **Webhooks** and add a webhook.
2. Paste the Payrails notification URL.
3. Subscribe to these events:
   * `payment_intent.requires_capture`, `payment_intent.succeeded` and `payment_intent.cancelled`
   * `payment_attempt.authorization_failed`
   * `refund.accepted`, `refund.succeeded` and `refund.failed`
4. Save the webhook and copy its secret key into the **Webhook Secret Key** field in Payrails.

***

## Request fields for Airwallex

Send these fields in the [authorize request](https://docs.payrails.com/reference/authorizeaction.md) for card payments, in addition to the standard authorize fields. **Required** fields must be present for the payment to succeed. Payrails sends **Optional** fields to Airwallex when you include them. For more about meta fields, refer to [Meta fields](https://docs.payrails.com/docs/orchestration/meta-fields.md).

| Field | Status | Description |
| :- | :- | :- |
| `amount` | Required | Sent to Airwallex as the amount and currency. Must be greater than zero, unless you're only storing the card. |
| `merchantReference` | Required | Up to 64 characters. Sent as the merchant order ID. |
| `meta.customer` | Required | On the customer's first payment. Payrails creates an Airwallex customer from `email`, `name`, `lastName`, `phone`, `country` and `reference`. |
| `instrument.holderName` | Optional | Sent as the card holder name. |
| `instrument.billingAddress` | Optional | Sent as the card billing address when it includes a country. |
| `meta.order` | Optional | Sent as the order products, discount, shipping and descriptor. |
| `meta.clientContext` | Optional | Sent as device data for Airwallex fraud checks. |
| `meta.risk.sessionId` | Optional | Sent as the device ID. Use the session ID from the [Airwallex fraud SDK](https://docs.payrails.com/docs/sdks/fraud-sdk.md#airwallex). |
| `meta.risk.threeDSMode` | Optional | `Force` or `Skip` requests or skips 3D Secure. |

***

## Enable the integration

**In Payrails**

* Select **Save account** to enable the integration.
* Confirm the integration shows as **Enabled**.

Your **Airwallex** integration is now ready to process payments.

***

## Next steps

1. Run a test card payment in the Airwallex demo environment.
2. Verify that:
   * The payment appears in the Airwallex web app.
   * The payment status updates correctly in Payrails.
3. Once verified in test mode, repeat the setup in live mode.

→ Continue to: [Test a payment](https://docs.payrails.com/docs/orchestration/payment-acceptance/test-payments.md)


## Related topics

- [Payrails Web Fraud SDK](https://docs.payrails.com/docs/sdks/fraud-sdk.md)
- [Payment providers](https://docs.payrails.com/docs/integrations/payment-providers.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.