> ## 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**. During the beta, self-service subscriptions and top-ups (PLG) are supported, as are sales-led (SLG) flows, but invoices generated from enterprise contracts aren't synced to Airwallex yet. Coupons aren't supported yet.
</Note>

## How it works

### Self-service subscriptions and credit top-ups (PLG)

1. The customer selects a plan or top-up and enters their payment details during checkout, in Airwallex's embedded payment form (see [Implementing checkout](#implementing-checkout)).
2. Stigg attempts to provision the subscription or credit grant and generates an invoice for it.
3. Stigg pushes the invoice to Airwallex, and Airwallex charges the customer's saved payment method.
4. Airwallex reports the payment status back to Stigg.
5. Once payment is successful, the status of the subscription and top-up is updated and access is granted.
6. Recurring renewals follow steps 2–4 without any customer interaction.

```mermaid theme={null}
flowchart TD
    A[Customer selects plan or credit top-up amount] --> B[Checkout]
    B --> C[Payment method saved - Airwallex]
    C --> D[Subscription provisioned + invoice generated - Stigg]
    D --> E[Invoice pushed and payment collected - Airwallex]
    E --> F[Payment status synced back - Stigg]
```

### Enterprise contracts (SLG)

Subscriptions sold through [enterprise contracts](/documentation/managing-customers-and-subscriptions/contracts/overview) are managed and invoiced in Stigg as usual. During the beta, the invoices generated from enterprise contracts aren't synced to Airwallex, so payment for them isn't collected through Airwallex.

## Entity mapping

Your self-service product catalog is managed in Stigg, and Stigg also manages the subscription lifecycle. Neither is synced to Airwallex. The invoices Stigg generates are synced to Airwallex, which is responsible for collecting payment for them. Only customers, payment methods, invoices, and payments are created in Airwallex.

| 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 | Not supported during the beta. |
| 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 on, including `payment_intent.succeeded`. |

<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.
* **Stigg APIs:** 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.

### Using the Stigg APIs

To build your own checkout, collect the payment method with Airwallex's embedded payment form, attach it to the customer in Stigg, and then provision the subscription:

1. **Prepare the payment form.** Call the `preparePaymentMethodForm` GraphQL mutation with the customer ID. When Airwallex is the invoicing integration, the response contains an `AirwallexPaymentMethodForm` with:
   * `clientSecret`: the client secret the Airwallex payment form initializes and confirms against.
   * `metadata.intentId`: the Airwallex payment intent ID.
   * `metadata.customerId`: the Airwallex customer ID that the payment method is saved under.
   * `metadata.currency`: the currency of the payment intent.
   * `metadata.env`: the Airwallex environment to initialize the SDK against (`demo` or `prod`).
2. **Render the Airwallex payment form.** Use Airwallex's client-side SDK to mount its embedded payment element in **recurring** mode, passing the values from step 1. When the customer confirms, Airwallex returns a payment consent ID (`cst_...`).
3. **Attach the payment method to the customer.** Call `attachCustomerPaymentMethod` (GraphQL) or `POST /api/v1/customers/{id}/payment-method` ([REST](/api-and-sdks/api-reference/rest/introduction)) with the consent ID as the `paymentMethodId` and `AIRWALLEX` as the `vendorIdentifier`. The consent becomes the customer's default payment method for future charges.
4. **Provision the subscription.** [Provision the subscription](/api-and-sdks/integration/backend/subscriptions) in Stigg as usual. Stigg generates the invoice and Airwallex charges the saved payment method.

<Note>
  `preparePaymentMethodForm` is currently available only in the GraphQL API.
</Note>

<Warning>
  Detaching a payment method isn't supported for Airwallex yet. To replace a customer's payment method, attach a new one. It becomes the customer's default payment method for future charges.
</Warning>

## 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.

## 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)