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

> Connect your app to GoCardless, a bank payments provider, to collect one-off payments and recurring direct debits from your Lovable app.

[GoCardless](https://gocardless.com/) is a payments provider that collects money from your customers' bank accounts by direct debit or Instant Bank Pay. Instant Bank Pay is a one-off payment the customer approves in their banking app.

The GoCardless connector lets your Lovable app set up those payments in your own GoCardless account. Your app sends customers to GoCardless's hosted payment pages and follows each payment's status. The connector is designed for apps that bill customers from their bank account, such as memberships, rent, and invoices.

GoCardless 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 GoCardless, your app can:

* Collect a one-off payment and send the customer to GoCardless's hosted payment page
* Set up a direct debit mandate, the customer's permission to collect future payments from their bank account
* Create monthly or yearly subscriptions on a mandate
* Update orders and memberships when GoCardless reports that a payment was confirmed, failed, or paid out
* Retry a failed request without charging a customer twice
* List payments, mandates, and payouts (the collected funds GoCardless pays into your bank account), for example to find failed payments or canceled mandates

The connection covers the rest of the GoCardless payments API too, so you can also ask Lovable to build refunds or installment schedules (a payment split into parts) with it.

If you want card payments, [Lovable payments](https://docs.lovable.dev/features/payments.md) can set up Stripe or Paddle for you instead. Built-in payments require the Pro plan or higher. When you ask Lovable to add payments without naming a provider or direct debit, it recommends those built-in payments.

## Common use cases and example apps

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

| Example app | Example prompt | Description |
| :- | :- | :- |
| **Club membership** | *Use GoCardless and build a sign-up flow where new members set up a monthly direct debit for their membership fee.* | **Collect membership fees every month.** The app sets up a mandate on GoCardless's hosted page, starts a monthly subscription, and updates the member's status from GoCardless. |
| **Invoice payment** | *Use GoCardless and build an invoice page where customers pay their invoice by bank payment.* | **Get paid for invoices from the customer's bank account.** The app creates a payment for the invoice amount and marks the invoice paid when GoCardless confirms it. |
| **Rent collection** | *Use GoCardless and build a tenant portal that collects monthly rent by direct debit.* | **Collect rent on a fixed schedule.** The app sets up a mandate for each tenant and a monthly subscription for the rent. |
| **Service plans** | *Use GoCardless and build a sign-up page for my yearly boiler service plan with payment by direct debit.* | **Sell recurring service plans.** The app signs customers up, sets up a yearly subscription, and shows which plans were canceled. |
| **Failed payments overview** | *Use GoCardless and build an admin page that lists customers whose last payment failed or whose mandate was canceled.* | **Follow up on failed payments.** The app reads payments and mandates from your GoCardless account and lists the customers who need attention. |
| **Payouts dashboard** | *Use GoCardless and build a dashboard that shows recent payouts and the payments in each one.* | **See what reached your bank account.** The app reads payouts from your GoCardless account and shows their amounts and status. |

## How to connect GoCardless

Who can create GoCardless 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 GoCardless connections, which is useful for keeping a sandbox connection for testing next to a live one, or for connecting different GoCardless accounts.

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.

When you're ready to take real payments, [unlink the sandbox connection](https://docs.lovable.dev/integrations/app-connectors.md#unlink-projects-from-a-connection) from the project and link the live one. Your app uses one GoCardless connection, so linking a second one does not switch it.

### Prerequisites

Before connecting GoCardless, make sure you have:

* A GoCardless account. For testing, a GoCardless sandbox account, which is separate from your live account.
* A GoCardless access token with read-write access, created in the sandbox or live account you will connect
* 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 collected through this connector go to your GoCardless account. GoCardless charges its transaction fees directly, not through Lovable.

### Step 1: Get a GoCardless access token

A GoCardless access token lets your Lovable app create and read payments in one GoCardless account. Sandbox and live are separate GoCardless environments, each with its own dashboard and its own access tokens. A sandbox token starts with `sandbox_` and moves no real money. A live token starts with `live_`.

Use a sandbox token while you build, and switch to a live token when you're ready to take real payments.

To create a GoCardless access token:

**1. Open the access token form**

Open the form in the account you want to connect: the [GoCardless sandbox dashboard](https://manage-sandbox.gocardless.com/developers/access-tokens?action=create) to test payments, or the [GoCardless dashboard](https://manage.gocardless.com/developers/access-tokens?action=create) to take real payments. Sign in if prompted.

**2. Create the token**

Give the token a descriptive name, for example `Lovable integration`, choose read-write access, and click **Create access token**. A read-only token can list payments but cannot set up payments or mandates.

**3. Copy the token**

Copy the token and store it securely. GoCardless shows it only once.

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

See GoCardless documentation for more: [GoCardless API reference](https://developer.gocardless.com/api-reference).

### Step 2: Connect GoCardless to Lovable

To connect GoCardless:

**1. Open GoCardless in Connectors**

Open [Connectors](https://lovable.dev/dashboard?connectors) and select **GoCardless**. 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, for example to `GoCardless Sandbox` or `GoCardless Live` when you keep a connection for each environment. The name is only used inside Lovable to identify the connection.

**4. Configure the connection**

Under **Configure connection**, enter:

1. **Access token**: paste your GoCardless access token. It must start with `sandbox_` or `live_`, and Lovable uses the matching GoCardless environment for it. **Open sandbox dashboard** next to the field opens the **Developers** page of the GoCardless sandbox dashboard.

**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 verifies the access token against the GoCardless API before saving the connection.

When connected, anyone building in a project can ask Lovable in the project chat to link their project to GoCardless. Linking follows the connection's access rules. Your Lovable apps can then set up payments and direct debits through GoCardless.

## How payments are confirmed

A direct debit payment is not instant. GoCardless confirms it over several working days, and a payment can still fail or be charged back after that. Instant Bank Pay payments don't have this delay.

Your app marks an order or membership as paid only when GoCardless reports it. Returning from the payment page doesn't mean the customer has paid.

GoCardless reports payment events by calling a webhook, a public address in your app. Lovable builds the webhook receiver and gives you its address. Your app uses a secret from GoCardless to check that each call comes from GoCardless.

To connect GoCardless's events to your app:

**1. Get the webhook address**

Ask Lovable in the project chat to build the GoCardless webhook receiver and to give you its address. Lovable may give you two addresses, one for testing and one for your published app.

**2. Create a webhook endpoint**

Open the **Developers** page of the GoCardless dashboard for the environment you collect payments in. Click **Create webhook endpoint** and paste the address. Create one endpoint for each address.

**3. Add the endpoint's secret**

Open the endpoint in the GoCardless dashboard and copy its secret. When Lovable asks for the webhook secret, enter it in the **Add secret** form rather than the chat. See [Understanding a secret prompt](https://docs.lovable.dev/features/secrets.md#understanding-a-secret-prompt).

## Limitations

The GoCardless connector cannot:

* Read bank balances or transactions. That is a separate GoCardless product, Bank Account Data, which this connector does not cover.
* Set up webhook endpoints in GoCardless for you. You create the endpoint in your GoCardless dashboard.
* Support platforms where each merchant connects their own GoCardless account. Each connection represents a single GoCardless account shared across all projects linked to it.

## Troubleshooting

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

> [accordion] GoCardless did not validate your credentials
>
> GoCardless rejected the access token you submitted. Check that you copied the whole token and that it has not been revoked in your GoCardless dashboard. Click **Show error** to see GoCardless's own response.

> [accordion] Requests that create payments fail with a permission error
>
> GoCardless returns a permission error when the access token is read-only. Create a token with read-write access in your GoCardless dashboard. Then the person who created the connection opens it in Lovable, pastes the new token under **Configure connection**, and clicks **Update**.

## Manage your GoCardless connection

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

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