# GoCardless

:::tip Available
This integration is active and ready to use in Frihet.
:::

Connect GoCardless to Frihet to manage SEPA direct debit collections. View mandates, payments, and clients directly from your ERP. Ideal for subscriptions and recurring payments with low fees.

## What is it for?

With GoCardless integrated:

- **Import payments** — Import GoCardless collections as invoices in Frihet with a click
- **Automatic deduplication** — Already imported payments are not duplicated (prefix `GC-`)
- **View payments** — View all your direct debit collections from Frihet
- **Manage clients** — Access client information with active mandates
- **Consult mandates** — See the status of each SEPA mandate (active, pending, cancelled)
- **Reconcile collections** — Associate GoCardless payments with invoices in Frihet
- **Sandbox mode** — Test the integration with fictitious data

## Requirements

- **Active GoCardless account** — [gocardless.com](https://gocardless.com)
- **API Access Token** — Generated from the dashboard
- **Frihet Pro or higher**

## Connect GoCardless with Frihet

### Step 1: Get your Access Token

1. Go to [manage.gocardless.com](https://manage.gocardless.com) (or [manage-sandbox.gocardless.com](https://manage-sandbox.gocardless.com) for testing)
2. Log in to your account
3. Go to **Developers** in the sidebar menu
4. Click on **Create** → **Access Token**
5. Select the **Read-only** scope (sufficient for querying data) or **Read-write** if you need to manage collections
6. Give it a name (e.g., "Frihet ERP")
7. Copy the generated token

:::caution Save the token
The Access Token is only shown once when created. Copy it before closing the window.
:::

### Step 2: Configure in Frihet

1. Go to **Settings** → **Integrations**
2. Search for **GoCardless**
3. Click on **Connect**
4. Paste your **Access Token**
5. Select the environment:
   - **Live** — For real data
   - **Sandbox** — For testing
6. Click on **Verify connection**

### Step 3: Verify connection

If the connection is correct, Frihet will show:

- Name of your GoCardless organization
- Number of active mandates
- Number of registered clients

## How it works

Frihet connects to the **GoCardless API v2** (version 2015-07-06) using Bearer authentication:

1. You provide your Access Token
2. Frihet sends the token in the `Authorization: Bearer <token>` header of each request
3. Payment, client, and mandate data is queried on demand
4. The token is stored encrypted (AES-256-GCM) in Frihet
5. All communication is performed over HTTPS

## Synchronized Data

| Data | Direction | Frequency |
|------|-----------|------------|
| Payments (collections) | GoCardless → Frihet | On demand |
| Clients | GoCardless → Frihet | On demand |
| SEPA Mandates | GoCardless → Frihet | On demand |
| Payment status | GoCardless → Frihet | On demand |

## Use cases

### Consultancy with monthly fees

You charge your clients a monthly fee via direct debit. From Frihet, you can see which payments have been successfully collected, which are pending, and which have failed, without leaving your ERP.

### SaaS with SEPA subscriptions

Your European clients prefer to pay by direct debit instead of card. GoCardless manages recurring collections, and Frihet shows you the status of each payment alongside the issued invoices.

### Verify mandates before invoicing

Before issuing a recurring invoice, check from Frihet if the client's mandate is still active. Avoid invoicing clients whose mandate has expired or been cancelled.

## Import payments to Frihet

You can import GoCardless payments as invoices in Frihet:

1. Go to **Settings** → **Integrations** → **GoCardless**
2. In the **Data** tab, click on **Import payments**
3. Frihet will download all payments and create invoices for each one
4. Payments already imported previously are automatically skipped (deduplication by `GC-{id}`)
5. Upon completion, you will see the exact number of imported payments

Imported payments include: amount, currency, date, reference, and status.

## Sandbox Mode

GoCardless offers a completely separate sandbox environment:

1. Register at [manage-sandbox.gocardless.com](https://manage-sandbox.gocardless.com)
2. Create an Access Token in the sandbox environment
3. Configure Frihet in "Sandbox" mode
4. Create test mandates and payments from the sandbox dashboard
5. Verify that the data appears correctly in Frihet

## GoCardless Payment Statuses

| GoCardless Status | Meaning |
|-------------------|-------------|
| `pending_submission` | Payment created, pending submission to the bank |
| `submitted` | Submitted to the bank, in process |
| `confirmed` | Collection successfully completed |
| `paid_out` | Funds transferred to your account |
| `failed` | The collection failed (insufficient funds, mandate cancelled, etc.) |
| `cancelled` | Cancelled before processing |

## Troubleshooting

### "Authentication error"

- Verify that the Access Token is correct and has not expired
- Make sure to use a **Live** token in Live mode and a **Sandbox** token in Sandbox mode
- If you regenerated the token in GoCardless, update it in Frihet

### "I don't see my payments"

- Check that you have payments registered in your GoCardless account
- Verify that the token has read permissions
- In sandbox, create test payments first

### "API version error"

- Frihet uses GoCardless API version 2015-07-06, which is stable and compatible
- If GoCardless notifies of API changes, we will update the integration

### "I want to disconnect"

1. Go to **Settings** → **Integrations** → **GoCardless**
2. Click on **Disconnect**
3. Optionally, revoke the Access Token from the GoCardless dashboard

## Next steps

- [Connect Stripe for card payments](./stripe)
- [Connect PayPal for international payments](./paypal)
- [Configure Plaid for direct bank connection](./plaid)