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

# Use Mollie as payment provider

> Connect Mollie to Firmhouse without copying API keys, turn on payment methods, and switch an existing API-key setup to Mollie Connect.

Use Mollie to take first payments and collect recurring subscription payments in Firmhouse. With **Mollie Connect**, you sign in to Mollie from Firmhouse and pick the website profile to use. You don't need to copy an API key.

This page covers:

* [Connecting Mollie for the first time](#connect-mollie)
* [Turning on payment methods](#turn-on-payment-methods)
* [Switching an existing API-key setup to Mollie Connect](#migrate-from-your-current-legacy-setup)

> [!NOTE]
>
> Mollie Connect is enabled automatically for new projects. For existing projects, contact Firmhouse support if you don't see **Connect with Mollie** or **Reconnect with Mollie**. It is not in **New Features**. Existing API-key setups keep working until you choose to switch.

## Before you start

* Have a [Mollie account](https://www.mollie.com/en) with a **website profile**: the shop or website in Mollie that receives the payments. Each profile has its own payment methods.
* Make sure you can sign in to the Mollie **organization** (your business in Mollie) that owns that profile.
* Make sure you can edit payment settings in Firmhouse.

## Connect Mollie

1. In Firmhouse, go to **Settings > Payments**.
2. Click **Connect a payment provider** and select **Mollie**.
   If you see an older payments form instead, select **Mollie** there.
3. Click **Connect with Mollie**, sign in to Mollie, and allow all the permissions Firmhouse asks for.
4. Back in Firmhouse, check the organization name, then choose your **Website profile**.
   No profiles listed? Create one in Mollie, return to Firmhouse, and click **Refresh profiles**.
5. Under **Payment mode**, choose **Live payments** to take real payments, or **Test payments** to try things out first.
6. Click **Save connection**.

Firmhouse shows **Connected with Mollie** with your organization, profile, and mode. Next, [check your payment methods](#turn-on-payment-methods).

If this is the first payment provider in your project, it becomes the default. If you already have another payment setup, the new account does **not** become the default automatically. See [Default account and country routing](#default-account-and-country-routing).

## Turn on payment methods

For Mollie Connect accounts, you can ask Mollie to turn on the main payment methods straight from Firmhouse. Open your Mollie account under **Settings > Payments** and scroll to **Payment methods**. You'll see **iDEAL**, **SEPA Direct Debit**, **Cards**, **Bancontact**, and **Pay by Bank**.

Still using an API key? Manage payment methods in your Mollie dashboard instead.

| Status | What to do |
| - | - |
| **Active** | Nothing. The method is ready. |
| **Not active** | Click **Request activation** if available. |
| **Under review** | Wait for Mollie to approve it. |
| **Complete onboarding**, **Action required**, or **Rejected** | Click **Open Mollie** and follow the steps there. |
| **Unavailable** or **Unknown** | Check the method in your Mollie dashboard. Don't assume it works yet. |

After you finish anything in Mollie, click **Refresh** to see the latest status. Mollie may still need to approve your business or a method before you can take live payments. A test payment that works doesn't mean the method is approved for live payments.

> [!WARNING]
>
> Turning a payment method on or off changes the Mollie profile itself. This also affects **live** payments, even if your Firmhouse account is in test mode, and every other shop or app that uses the same profile. Turning off a method can make new payments and recurring charges fail.

### Recurring bank payments need SEPA Direct Debit

iDEAL | Wero, Bancontact, and Pay by Bank only handle the first payment. To charge the customer's bank account again later, turn on **SEPA Direct Debit** on the same profile. If you don't, recurring payments fail. See [Recurring charges for iDEAL and SEPA](https://docs.firmhouse.com/explained/recurring-charges-sepa.md).

## Test and live payments

* **Test payments** never collect real money. Use them to try your checkout.
* **Live payments** charge customers for real. Mollie must approve your account and the payment methods you use.

To change the profile or mode later, open the account under **Settings > Payments** and click **Configure**. If Mollie asks you to sign in again, click **Reconnect Mollie** there.

When reconnecting a Connect account with completed live signups, you must use the same Mollie organization.

> [!WARNING]
>
> You can't switch between test and live if a subscription using the account has completed signup or is waiting for the customer to finish signup. This includes cancelled subscriptions with a completed signup. The lock protects saved payment details. If you need the other mode, add a separate account instead.
>
> When switching is allowed, it can still hide saved payment details and past payments. Contact Firmhouse support before you change the mode or profile of an account that has payment history.

Before you switch to another website profile, turn on the payment methods you need on that profile. New payments go through the new profile from then on.

## Migrate from your current legacy setup

Already using a Mollie API key? You can switch that setup to Mollie Connect with **Reconnect with Mollie**. Your payments keep running on the same Mollie profile in the same mode, so subscriptions continue as before.

Your API key keeps working until the switch is saved. If you cancel, if something fails, or if the attempt expires, nothing changes.

### Switch to Mollie Connect

1. Go to **Settings > Payments** and open your current Mollie setup:
   * **Legacy Mollie** (with a **Default** label): click **Edit**.
   * A saved Mollie account: open it and click **Configure**.
   * An older payments form: start on that page.
2. Under **Reconnect your existing Mollie account**, click **Reconnect with Mollie**.
   Save any other changes on the page first. This button doesn't save them.
3. Sign in to Mollie. Choose the organization that owns the profile your API key uses, and allow all requested permissions.
4. On **Confirm your Mollie reconnection**, check the **Website profile** and **Payment mode**. Firmhouse fills these in from your API key, and you can't change them here.
5. Click **Save connection**. Or click **Cancel** to keep using your API key.
6. Check that the account shows **Connected with Mollie**, the profile and mode you expect, and your payment methods. Verify checkout and recurring payments in that mode. Live mode collects real money; don't switch modes just to test the conversion.

### What changes and what stays the same

**Stays the same:**

* Your Mollie profile and test or live mode
* The links between Firmhouse and your Mollie customers, mandates, and payments. Firmhouse doesn't create new ones.
* Which account each subscription uses, your default account, and your country settings. A saved account keeps its name and settings. A **Legacy Mollie** setup becomes a saved **Mollie** account and stays your default.

**Changes:**

* Firmhouse signs in to Mollie with Connect instead of your API key.
* Firmhouse deletes the API key from its settings. The key still exists in Mollie, so you can revoke it there if you no longer use it anywhere else.
* You can't switch back to the API key yourself. Contact Firmhouse support if you need help.
* After the switch, the normal Connect rules apply, such as the [test and live mode lock](#test-and-live-payments).

> [!WARNING]
>
> Reconnecting doesn't move your subscriptions to another Mollie profile or organization. Firmhouse also can't check that every older customer and payment belongs to your current profile. After switching, check your payment flows. If older payment details can't be found, contact Firmhouse support.

### If reconnecting fails

If you see **Mollie reconnection failed**, check that you signed in to the organization that owns your current profile. If the message names an organization, it is the one you just signed in to, not your existing one. Try again with the right organization, or contact Firmhouse support.

If your payment settings changed while you were signing in, start **Reconnect with Mollie** again from the settings page.

In every failed case, your API key keeps working. Don't delete the key or change your default account to work around a failure.

### Keep using your API key

You don't have to switch. To check or update an existing API-key setup:

1. Go to **Settings > Payments**.
2. Click **Edit** on **Legacy Mollie**, or open a saved Mollie account and click **Configure**.
3. Check the profile, mode, and **Currently active payment methods**. Manage payment methods in your Mollie dashboard.
4. To replace the key, copy it from **Developers > API keys** in Mollie. Keys starting with `test_` use test mode, and keys starting with `live_` use live mode.

Contact Firmhouse support before you replace the key on an account with subscriptions. A different key can stop existing subscriptions from being charged. A live key can't be changed once customers have signed up with it. Never share API keys in support messages.

### Adding a separate Connect account is not the same

You can add a new Mollie account next to your API-key setup with **Connect a payment provider > Mollie**. This does **not** switch your existing setup. It doesn't move subscriptions or saved payment details, and it doesn't change your default account or country settings.

To switch your current setup, use [Reconnect with Mollie](#switch-to-mollie-connect). Don't make the new account your default just to replace your API key.

## Default account and country routing

Your **default** account is marked with **Default** under **Settings > Payments**. Checkout uses it, unless country routing applies.

* **Country routing** (when enabled for your project): checkout uses the account set up for the customer's shipping country. Countries without their own account use the default. Set countries for a non-default account under **Configure > Countries**.
* **Subscriptions linked to an account** keep using that account.
* **Subscriptions not linked to an account** follow the default and country settings. Changing these settings can move them to another account.

To change the default, open an account and click **Make default**. If Adyen AutoRescue is on, turn it off first.

> [!WARNING]
>
> Changing the default doesn't move saved payment details or past payments. The confirmation shows how many subscriptions will start using the new account. Their next charges can fail, and older payments may no longer be checked or refunded. Contact Firmhouse support before you change a working default or country routing.

Click an account's **Subscriptions** count to see which subscriptions use it.

## Use Mollie with Shopify

Use the same Mollie organization, website profile, and mode in Firmhouse and in your Shopify Mollie apps. Connecting Mollie in Firmhouse doesn't install the Shopify apps. See [Set up local payment methods on Shopify](https://docs.firmhouse.com/shopify/setup-local-payment-methods.md).

The **Configure Mollie** button in the Shopify payment setup opens:

* your **Legacy Mollie** settings, if that setup is active. This happens even if you also have a separate Connect account.
* otherwise, your saved Mollie account. Firmhouse opens the default account if it uses Mollie, or the oldest Mollie account if not.
* for a new project without Mollie, the setup for a new Mollie account. Finish **Connect with Mollie** and click **Save connection** to complete it.

To open another Mollie account, select it under **Settings > Payments**.

## Troubleshooting

| Problem | What to do |
| - | - |
| No **Connect with Mollie** button | If you already use an API key, look for **Reconnect with Mollie** in its settings. Otherwise, contact Firmhouse support to check if Connect is available for your project. |
| No website profiles to choose from | Create a profile in your Mollie organization, then click **Refresh profiles**. |
| Account shows **Profile: Not selected** | Open the account, click **Configure**, then choose a profile and mode and save. |
| **Mollie could not be connected** | Try again, sign in to the right organization, and allow all permissions. If it keeps failing, contact Firmhouse support. |
| **Mollie reconnection failed** | Sign in to the organization that owns your current profile. See [If reconnecting fails](#if-reconnecting-fails). |
| Test payments work, live payments don't | Check that the account is in live mode and that Mollie has approved your account and the payment methods. |
| Recurring bank payments fail | Check that SEPA Direct Debit is active on the profile and that the subscription uses the right account. See [Update a subscription's payment method](https://docs.firmhouse.com/manage/subscriptions/update-payment-method.md). |
| **Configure Mollie** in the Shopify setup opens an API-key form | This is expected while **Legacy Mollie** is active. Open other Mollie accounts under **Settings > Payments**. |

## Related articles

* [Recurring charges for iDEAL and SEPA](https://docs.firmhouse.com/explained/recurring-charges-sepa.md)
* [Set up local payment methods on Shopify](https://docs.firmhouse.com/shopify/setup-local-payment-methods.md)
* [Supported subscription payment methods](https://docs.firmhouse.com/explained/supported-payment-methods.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.