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

> Connect your app to Adyen, a payments company, to take cards, wallets, and local payment methods such as iDEAL from your Lovable app.

[Adyen](https://www.adyen.com/) is a payments company for online checkout. The Adyen connector lets your Lovable app create checkout sessions and payment links, take cards, wallets, and local payment methods, and issue refunds. It's designed for apps whose owners already take payments with an Adyen merchant account.

If you haven't chosen a payment provider, start with [Lovable payments](https://docs.lovable.dev/features/payments.md).

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

With Adyen, your app can:

* Create a checkout session and take payment in the page with Drop-in (Adyen's in-page payment form), or send the customer to an Adyen payment link
* Offer the payment methods enabled on your merchant account, including cards, wallets, and iDEAL
* Confirm a payment from Adyen's signed webhook or from the checkout session status before marking an order paid. A webhook is the notification Adyen sends your app. HMAC (hash-based message authentication code) is how your app confirms Adyen sent that notification
* Capture (take the money after the payment is approved), refund, or cancel a payment
* Charge a card stored for that customer on a later payment

It's a good fit for shops, invoicing tools, and booking apps that take payment online.

## Common use cases and example apps

These examples show what you can build with Adyen, each with a prompt to start from.

| Example app | Example prompt | Description |
| :- | :- | :- |
| **Webshop checkout** | *Use Adyen and build a checkout for my shop so customers can pay for their cart with a card or a wallet.* | **Take payment for a cart in the page.** The app creates a checkout session and shows Drop-in for the methods on your merchant account. |
| **Invoice payment link** | *Use Adyen and build an invoice page that sends the customer an Adyen payment link.* | **Collect an invoice without a card form in your app.** The app creates a payment link and sends the customer to Adyen to pay. |
| **Event tickets** | *Use Adyen and build a ticket page where visitors pay with iDEAL and get a confirmation after Adyen confirms the payment.* | **Sell tickets with a local payment method.** The app creates the payment for the selected tickets and confirms the order after Adyen confirms the payment. |
| **Booking deposit** | *Use Adyen and build a booking form that takes a deposit to confirm the appointment.* | **Hold a booking with a paid deposit.** The app charges the deposit through Adyen and confirms the booking after Adyen confirms the payment. |
| **Order refunds** | *Use Adyen and build an orders page where my team can refund a paid order.* | **Refund a payment from your own orders page.** The app refunds the Adyen payment for that order and records the refund. |
| **Returning customer** | *Use Adyen and build a checkout that stores a customer's card and charges it on their next order.* | **Charge a stored card on a later order.** The app stores the card during the first checkout and charges that stored card on the next order. |

## How to connect Adyen

Who can create Adyen 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 multiple Adyen connections using different API keys, which is useful for separating test and live payments or connecting more than one merchant account.

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 Adyen, make sure you have:

* An Adyen company account, the account for your business. The company account holds one or more merchant accounts, and each merchant account processes its own payments. This connection uses one merchant account
* A web service API key from the same Customer Area (Adyen's dashboard) as that merchant account
* Permission to **create connections** in your Lovable workspace (see [Who can create connections and clients](https://docs.lovable.dev/integrations/admin-controls.md#who-can-create-connections-and-clients))

> [!NOTE]
>
> Payments through this connector are processed by your Adyen merchant account. Billing is handled directly by Adyen, not Lovable.

### Step 1: Get your Adyen credentials

A connection needs a web service API key and the merchant account code from the same environment. Use the test Customer Area while you build, and the live Customer Area for real charges.

To create the credentials:

**1. Open your Customer Area**

Sign in to the [test Customer Area](https://ca-test.adyen.com/ca/ca/config/api_credentials) or the [live Customer Area](https://ca-live.adyen.com/ca/ca/config/api_credentials), and select your company account. You need the **Manage API credentials** role or the **Merchant admin** role.

**2. Create a web service credential**

Go to **Developers > API credentials** and open the **Payments** tab. **Payments** is for credentials that call Adyen's Checkout API. The **Platforms** tab is for Balance Platform, which this connector cannot call. Select **Create new credential**, and under **Credential type** select **Web service user**, the credential type for Checkout API calls. Select **Create credential**.

**3. Generate an API key**

Under **Server settings > Authentication**, select the **API key** tab. Adyen shows the API key only once. Select **Generate API key**, copy the key, store it securely, then select **Save changes**.

If you restrict the credential with an allowed IP range, allow the ranges in [IP allowlisting](https://docs.lovable.dev/integrations/security.md#ip-allowlisting). A key that blocks those addresses fails when you click **Connect**.

**4. Copy the merchant account code**

In the upper-left account switcher, select your company account name. The names under it are your merchant account codes. Copy the code from the same Customer Area as the API key. You can also open **Settings > Merchant accounts**. See [Account structure](https://docs.adyen.com/account/account-structure).

**5. Copy a client key, a webhook HMAC key, or both**

Copy a client key when customers pay in the page, a webhook HMAC key when the app should treat a notification as paid, or both.

For the client key, open the same credential. Under **Client settings > Authentication**, select the **Client key** tab, then select **Generate client key**. Under **Add allowed origins**, add each origin where customers pay, including `https://your-app.lovable.app` and `https://yourdomain.com`, then select **Save changes**.

Copy the HMAC key here when a **Standard webhook** already exists. Go to **Developers > Webhooks**, select it, select **Edit webhook**, and copy the hex HMAC key under **Security**. To create the webhook, connect first, then follow [Add a webhook](#add-a-webhook).

**6. Copy the live URL prefix**

For a live connection, in the live Customer Area go to [Developers > API URLs > Prefix](https://ca-live.adyen.com/ca/ca/config/api_urls). Copy the label before `-checkout-live`. From `https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com/checkout`, copy `1797a841fbb37ca7-AdyenDemo`. See [Live endpoints](https://docs.adyen.com/development-resources/live-endpoints).

> [!WARNING]
>
> Your API key functions like a password. Keep it secure and never share it publicly. You'll need it in the next step.

See Adyen's documentation for more: [API credentials](https://docs.adyen.com/development-resources/api-credentials).

### Step 2: Connect Adyen to Lovable

Use the credentials from Step 1, all from the same Customer Area.

**1. Open Adyen in Connectors**

Open [Connectors](https://lovable.dev/dashboard?connectors) and select **Adyen**. 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 for the connection, which you can change. The name is only used inside Lovable to identify the connection. A name such as `Adyen test` or `Adyen live` keeps the two environments apart.

**4. Configure the connection**

Under **Configure connection**, set:

1. **Environment**: choose **Test** or **Live**. **Test** is selected by default. Test is for the Adyen test Customer Area, and **Live** is for real charges. The API key and merchant account must come from that same environment.
2. **API key**: paste the web service API key from that environment.
3. **Merchant account**: paste the merchant account code.
4. **Client key** (optional): paste the client key for Drop-in. A test key starts with `test_`, and a live key starts with `live_`. The field shown matches **Environment**. Without a client key, your app sends customers to an Adyen payment link instead of showing Drop-in in the page.
5. **Webhook HMAC key** (optional): paste the hex key. Add it when your app should mark orders paid from Adyen's notifications.
6. **Live URL prefix**: shown only when **Environment** is **Live**, and required then. Paste the prefix you copied. The field rejects a full URL, dots, slashes, and spaces.

**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 the API key by requesting the payment methods for the merchant account, then saves the connection. The key and the merchant account must belong to the same environment.

When Adyen is busy or unavailable, Lovable saves the connection without that check. A wrong key then fails on the app's first request, not at **Connect**.

When connected, anyone building in a project can ask Lovable in the project chat to link their project to Adyen. Linking follows the connection's access rules. Your Lovable apps can then create checkout sessions and payment links, take the payment methods on your merchant account, and issue refunds.

### Add a webhook

Ask Lovable in the project chat to add an Adyen webhook. Lovable gives you the URL to paste under **Server configuration** in Adyen. Adyen requires that URL before **Save configuration**. See [Verify HMAC signatures](https://docs.adyen.com/development-resources/webhooks/secure-webhooks/verify-hmac-signatures).

Under **Security** on that webhook, copy the hex HMAC key. Generating a new key replaces the one already on the webhook. Open the connection, click **Edit** next to **Webhook HMAC key** under **Configure connection**, paste the key, and click **Update**.

## Limitations

The Adyen connector cannot:

* Take in-person payments on Adyen terminals, manage accounts and users, pay out funds, or download reports
* Support per-end-user Adyen login. Each connection represents a single Adyen merchant account shared across all projects linked to it.

## Troubleshooting

Use these checks when connecting fails or an Adyen request returns an unexpected status.

> [accordion] Adyen did not validate your credentials
>
> Adyen rejected the key when Lovable checked it. Click **Show error** to read Adyen's response. When the API key and the merchant account come from different Customer Areas, paste both from the same environment, test or live, then click **Connect** again.

> [accordion] The API key blocks Lovable's addresses
>
> An allowed IP range on the API credential rejects Lovable when those addresses are missing. Add the ranges in [IP allowlisting](https://docs.lovable.dev/integrations/security.md#ip-allowlisting), select **Save changes** in the Customer Area, then click **Connect** again.

## Manage your Adyen connection

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

* **Unlink projects** to remove Adyen 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 Adyen 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.
