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

# Airwallex

[Airwallex](https://www.airwallex.com/) is a global payment service provider (PSP) with native support for cross-border and FX payments.

Stigg's native integration with Airwallex allows you to collect payments for self-service subscriptions, sales-led contracts and credit top-ups using Airwallex.

<Note>
  The Airwallex integration is currently in **Public Beta.**
</Note>

## How it works

1. When customers subscribe to a plan, contract or attempt to top-up credits Stigg generates an invoice.
2. Stigg pushes the invoice to Airwallex.
3. Payments are collected using Airwallex.
4. Airwallex reports the payment status back to Stigg.
5. Once payment is successful, the status of the subscription and top-up is updated accordingly and access is granted.
6. Recurring renewals follow steps 1–4 without any customer interaction. When **usage-based pricing** is defined, generated invoices will reflect the reported usage.

<Note>
  Customers' payment details are stored directly in Airwallex. Stigg does not store this information.
</Note>

```mermaid theme={null}
sequenceDiagram
    autonumber
    actor Customer
    participant App as Your application
    participant Stigg
    participant Airwallex

    Customer->>App: Subscribe to plan / contract / top-up credits
    App->>Stigg: Subscribe to plan / contract / top-up credits
    Stigg->>Stigg: Provision subscription / contract / top-up<br/>(status: pending payment)
    Stigg->>Airwallex: Create invoice
    Airwallex->>Customer: Collect payment
    Airwallex->>Stigg: Update payment status
Stigg->Stigg: Entitlements updated / credits granted
    Stigg-->>App: Access updated
    App-->>Customer: Access updated
```

## Entity mapping

| Stigg Entity | Airwallex Entity | Notes |
| :- | :- | :- |
| Feature | N/A | Managed within Stigg. |
| Product | N/A | Managed within Stigg. |
| Plan / Add-on | N/A | Managed within Stigg. |
| Coupon | N/A | Managed within Stigg. |
| Customer | Customer | Created in Airwallex the first time a customer adds a payment method or checks out.<br />Payment methods are stored directly in Airwallex. |
| Subscription | N/A | Managed within Stigg. |
| Contract | N/A | Managed within Stigg. |
| Credit grant | N/A | Managed within Stigg. |
| Invoice | Invoice | Created in Airwallex when Stigg issues an invoice. |

## Setting up the integration

Setting up the integration takes two steps: get your credentials from Airwallex, then enter them in Stigg.

### 1. Get your credentials from Airwallex

In the Airwallex dashboard for the environment you're connecting (sandbox or production):

1. Go to **Developer > API keys** and click **New scoped key**.
2. Give the key a name, grant it the [permissions listed below](#permissions-required), and create it.
3. Copy the key's **Client ID** (shown in the API keys table) and the generated **API key**.
4. Obtain your **Org ID** (`org_...`). You can find it on the API key's **Overview** page, under **Access to > Organisation**.
5. Go to **Settings**, and under **Entities**, open the account you want Stigg to route checkouts to. Copy the **Account ID** (`acct_...`) from the **Account details** panel.

You'll also need the **API URL** for the Airwallex environment you're connecting:

| Environment | API URL |
| :- | :- |
| Sandbox | `https://api.sandbox.airwallex.com` |
| Production | `https://api.airwallex.com` |

<Warning>
  Airwallex only shows the API key once. Store it securely. If it's lost, generate a new scoped key and reconnect the integration in Stigg.
</Warning>

#### Permissions required

Grant the scoped API key the following permissions, at the level shown for each:

| Permission | Level | Access | Notes |
| :- | :- | :- | :- |
| Payment Acceptance | Account | Read and write | Used to process the payment for each checkout and invoice. Enabled by default on every key and can't be removed. |
| Billing > Customers | Global | Read and write | Used to create the customer in Airwallex. |
| Billing > Invoices | Global | Read and write | Used to push the invoices Stigg generates to Airwallex. |
| Billing > Payment Sources | Global | Read and write | Used to save a customer's payment method for recurring charges. |
| Billing > Billing Checkouts | Global | Read and write | Used to create the checkout session for Airwallex's embedded payment form. |
| Webhooks | | Read and write | Used to register the webhook endpoint Stigg listens to. |

<Warning>
  If a permission is missing or granted at the wrong level, the integration is flagged with a setup error (for example, "Insufficient permissions for subscribing to payment\_intent.succeeded"). To fix it, reconnect with a correctly scoped key.
</Warning>

### 2. Enter the credentials in Stigg

1. In the [Stigg app](https://app.stigg.io), go to **Integrations** and click **Add integration**.
2. Find **Airwallex** in the list of available integrations and select it.
3. Fill in the credentials from step 1:
   * **Client ID**
   * **API Key**
   * **API URL**
   * **Org ID**
   * **Account ID**
4. Click **Connect**.

That's it. The integration shows as **Active** in your list of active integrations.

## Implementing checkout

You can collect payment through Airwallex in one of two ways:

* **Stigg Checkout widget:** the quickest option, with no payment-specific code on your side.
* **Custom checkout experience:** for a fully custom checkout experience in your own UI.

Either way, Stigg generates the invoices and Airwallex collects the payment for them.

### Using the Stigg Checkout widget

Render Stigg's [checkout widget](/documentation/snap-in-widgets/checkout) as you normally would.

When Airwallex is your environment's invoicing integration, the widget automatically renders Airwallex's embedded payment form, saves the customer's payment method in Airwallex, and provisions the subscription in Stigg.

No Airwallex-specific configuration is needed.

### Custom checkout experience

To build your own checkout:

1. [Collect the payment method with Airwallex's embedded payment form](https://www.airwallex.com/docs/payments/integration-options/web-checkout/save-and-reuse-payment-details)
2. Attach the payment method to the customer with the consent ID as the `paymentMethodId` and `AIRWALLEX` as the `vendorIdentifier`. The consent becomes the customer's default payment method for future charges.
3. Provision the subscription or credit grant in Stigg.

## Accessing Airwallex entities from Stigg

In the Stigg app, clicking on the link of the "billing ID" property will open the relevant entity in Airwallex:

* **Customers** link to the customer in Airwallex.
* **Subscriptions** and **credit grants** link to their invoice in Airwallex.

## Beta limitions

The following flows are not currently supported:

1. Creating subscriptions and contracts with payment links.
2. Applying discounts using coupons.

<Note>
  We're actively working to lift these limitations.
</Note>

## Removing the integration

To remove the integration, click on the dotted menu icon and select the **Remove** action.

Confirm the action by clicking on the **Remove** button in the opened modal.

<Warning>
  Removing the integration doesn't affect already-collected payments or issued invoices, but new checkouts and payment-method updates can no longer be routed to Airwallex until it's reconnected.
</Warning>

## Related articles

<Card title="Add a checkout experience to my application" icon="cart-shopping" horizontal href="/guides/i-want-to/add-a-checkout-experience-to-my-application" />

<Card title="Checkout widget" icon="credit-card" horizontal href="/documentation/snap-in-widgets/checkout" />


## Related topics

- [Integrations](/documentation/native-integrations/overview.md)
- [C#](/api-and-sdks/changelog/backend-rest/csharp.md)
- [Get a list of credit grants](/api-reference/credit-grants/get-a-list-of-credit-grants.md)
- [Void credit grant](/api-reference/credit-grants/void-credit-grant.md)
- [Create a credit grant](/api-reference/credit-grants/create-a-credit-grant.md)