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

# Connect your app to Airwallex

> Connect your app to Airwallex to accept payments, share payment links, manage subscriptions and invoices, and display balances by currency.

[Airwallex](https://www.airwallex.com/) lets businesses accept and manage payments in multiple currencies. If you already take payments with Airwallex, you can use the same account for checkout, invoicing, and reporting in your Lovable app. If you haven't chosen a payment provider, start with [Lovable payments](https://docs.lovable.dev/features/payments.md).

Airwallex is available as an [app + chat connector](https://docs.lovable.dev/integrations/app-connectors.md): one shared connection that works in [Chats](https://docs.lovable.dev/features/chats.md), in the project chat while you build, and in your published apps. If you ask for balances or recent payments in Chats or the project chat, Lovable offers to build a page in your app rather than display live figures there.

## Common use cases and example apps

Choose a prompt based on how your customers pay or what your team needs to track.

| Example app | Example prompt | Description |
| :- | :- | :- |
| Ticket checkout | *Use Airwallex and build a ticket shop that confirms a booking after the customer pays.* | **Take card and local payments.** The app sends customers to Airwallex checkout and checks the payment status before issuing tickets. |
| Deposit requests | *Use Airwallex and build a booking tool that gives each customer a link to pay their deposit.* | **Collect a deposit without building a checkout page.** The app creates a shareable payment link for the booking amount and currency. |
| Membership billing | *Use Airwallex and build a membership app that bills customers monthly.* | **Collect recurring membership fees.** The app creates a billing customer and a subscription at the selected price. |
| Invoice tracker | *Use Airwallex and build a billing dashboard that shows my finance team which invoices are unpaid.* | **Find invoices that need follow-up.** The app lists invoices from Airwallex and groups them by status. |
| Currency balances | *Use Airwallex and build a private dashboard that shows our current balance in each currency.* | **Check available funds without switching accounts.** The app reads balances from the connected account and displays each currency separately. |

> [!WARNING]
>
> The connection gives your app access to Airwallex. It does not control who can see the financial data your app displays. For an internal dashboard, ask Lovable to [require sign-in](https://docs.lovable.dev/features/authentication) and check that the viewer belongs to your finance team before returning invoices or balances.

## How to connect Airwallex

Who can create Airwallex connections depends on your plan and workspace settings. App + chat connectors are available by default. On Business and Enterprise plans, [Who can create connections and clients](https://docs.lovable.dev/integrations/admin-controls.md#who-can-create-connections-and-clients) starts at **Admins**. Some Enterprise workspaces start at **No one**, which disables the connector. An admin or owner changes it in **Connectors → Admin settings → App + chat connectors**.

You can create separate connections for sandbox and production. Sandbox payments move no real money.

When the connection is created, you can [link it to the projects](https://docs.lovable.dev/integrations/app-connectors.md#link-a-connection-to-a-project) where you want to use it. Anyone building in a project can ask Lovable in the project chat to link their project to it. Linking follows the connection's access rules.

### Prerequisites

Before connecting Airwallex, make sure you have:

* An Airwallex account and access to its developer settings. Ask an Airwallex owner, admin, or developer to create the key if you don't have access.
* Airwallex Billing enabled on the account if you want your app to manage subscriptions or invoices.
* Permission to [create connections in your Lovable workspace](https://docs.lovable.dev/integrations/admin-controls.md#who-can-create-connections-and-clients).

> [!NOTE]
>
> Airwallex, not Lovable, bills your Airwallex account for processing production payments.

### Step 1: Get your Airwallex credentials

Airwallex issues separate credentials for sandbox and production. Start with a sandbox key to test your app.

**1. Open API keys in Airwallex**

For test payments, sign in to the [Airwallex sandbox](https://www.sandbox.airwallex.com/app/) and open **API keys** in your developer settings. For real payments, open [production API keys](https://www.airwallex.com/app/account/developer/api-keys) instead.

**2. Create a scoped key**

A scoped key limits your app to the resources and actions you select. An admin key grants all API permissions for the account or organization it belongs to. Click **New scoped API key** and enter a name.

Choose permissions for the tasks your app performs. For example:

* To list invoices, grant **Read** for **Invoices**.
* To create payment links, select the account that accepts payments and grant **Write** for **Payment Links**.

If your app does both, grant both permissions on the same key.

**3. Save the client ID and API key**

Click **Create**. Store the API key securely and keep the client ID paired with it. Airwallex shows the key only once.

If the key covers several accounts, open **Settings → Account details** for the account your app should use. Copy the account ID that starts with `acct_`, not the organization ID.

For other tasks, use [Airwallex’s API key scopes](https://www.airwallex.com/docs/developer-tools/api/api-key-scopes) to find the resource and permission your app needs.

### Step 2: Connect Airwallex to Lovable

Enter your credentials in the connection form, not in the project chat.

**1. Open Airwallex in Connectors**

Open [Connectors](https://lovable.dev/dashboard?connectors) and select **Airwallex**. For the other places to open the catalog from, see [Where to find connectors](https://docs.lovable.dev/integrations/introduction#where-to-find-connectors).

**2. Add a connection**

Click **Connect** on the connector page. The form is split into collapsible sections, **Details**, **Configure connection**, and **Sharing**.

**3. Name the connection**

Under **Details**, Lovable fills in a name, which you can change. Choose a name such as `Airwallex sandbox` so you can tell it apart from your production connection.

**4. Configure the connection**

Under **Configure connection**, enter:

1. **Environment**: keep **Sandbox (testing)** for test payments or select **Production** for real payments.
2. **Client ID**: enter the client ID for the selected environment.
3. **API key**: enter the key paired with that client ID.
4. **Account ID**: if your key is linked to several accounts, expand **Advanced settings** and enter the account ID you copied. Otherwise, leave it blank.

**5. Choose who can use this connection**

Under **Sharing**, the connection is private to you by default and shows a **Private** label. To share it, click **Share with others**. Then add workspace members by email, or click **Invite entire workspace** to make the connection available to everyone in your Lovable workspace.

See [Who can use connections and clients](https://docs.lovable.dev/integrations/admin-controls.md#who-can-use-connections-and-clients) for more information.

**6. Connect**

Click **Connect** at the bottom of the form. Lovable checks that Airwallex accepts the client ID and API key. Passing this check does not confirm that the key can access the intended account or perform the actions your app needs.

If your app gets a permission error, check the key's permissions in Airwallex and grant any missing permission. If the key covers several accounts, enter the intended account's ID under **Advanced settings** in the Lovable connection.

When connected, anyone building in a project can ask Lovable in the project chat to link their project to Airwallex. Linking follows the connection's access rules. To try checkout without charging a customer, link your sandbox connection and use an [Airwallex test card](https://www.airwallex.com/docs/payments/test-and-go-live/test-card-numbers).

## Receive payment updates after checkout

If your app confirms orders or bookings after payment, set up payment notifications. Airwallex can notify your app when a payment succeeds even if the customer never returns from checkout. Creating the connection does not register your app for notifications.

**1. Get the notification URL**

Ask Lovable to add a webhook endpoint to receive and verify Airwallex notifications. Ask for its URL and the events it handles.

**2. Register the URL in Airwallex**

In the Airwallex environment that matches your connection (sandbox or production), go to **Developer → Webhooks** and click **New webhook**. Name the webhook and enter the URL Lovable gave you under **Notification URL**.

Select the events your endpoint handles, such as `payment_intent.succeeded` for a successful payment. Click **Submit**.

**3. Save the signing secret**

Copy the signing secret for that URL from Airwallex. Ask Lovable for a [secure secret form](https://docs.lovable.dev/features/secrets.md) and enter the secret there so your app can verify the notifications.

## Switch from sandbox to production

To accept real payments, [create a separate Airwallex connection](#step-2-connect-airwallex-to-lovable). Under **Environment**, select **Production** and enter your production client ID and API key. [Unlink your project from the sandbox connection](https://docs.lovable.dev/integrations/app-connectors.md#unlink-projects-from-a-connection), then ask Lovable in the project chat to link the production connection.

If your app sends customers to Airwallex hosted checkout, [publish the app](https://docs.lovable.dev/features/publish.md) after linking the production connection. Until you publish, the checkout page on your live site still opens Airwallex in sandbox mode.

If your app uses payment notifications, ask Lovable for the production webhook URL:

* For a webhook on your app's website, publish the webhook changes and use the published webhook URL, not the preview URL.
* For a Supabase Edge Function, use the deployed function's URL.

[Register that URL](#receive-payment-updates-after-checkout) in Airwallex production. Before accepting payments, copy the signing secret from the production webhook. Ask Lovable in the project chat for a [secure secret form](https://docs.lovable.dev/features/secrets.md) to update your app’s webhook signing secret. Paste the production secret into the form, not the chat.

## Limitations

The Airwallex connector cannot:

* Retrieve full card numbers for issued cards.
* Let each person using your app sign in to their own Airwallex account. The connection uses the account you configured.

## Manage your Airwallex connection

Connections are managed from [**Connectors**](https://lovable.dev/dashboard?connectors): select **Airwallex**, then open the connection.

* **Unlink projects** to remove Airwallex access from specific projects while keeping the connection available for others. See [Unlink projects from a connection](https://docs.lovable.dev/integrations/app-connectors.md#unlink-projects-from-a-connection) for the steps.
* **Delete the connection** to remove it from the workspace entirely. Deleting is permanent. It removes the credentials from all linked projects, and app features that use Airwallex stop working until a new connection is added. See [Delete a connection](https://docs.lovable.dev/integrations/app-connectors.md#delete-a-connection) for the steps and who can delete.
