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

# Using adyen as payment provider

This article explains how to start accepting one-time and recurring payments on Firmhouse by using Adyen as Payment Service Provider.

First of all, make sure you're logged into the correct Adyen environment you want to connect to your Firmhouse project. If you want to perform test payments, you need to be in the **ca-test** environment. For live payments, you need to be in the **ca-live** environment.

## In Adyen: Create an API (Webservice) User

The first thing you need to do is create an API user so that Firmhouse can connect to your Adyen account.

### Steps

1. In your Adyen account go to **Developers > API credentials** in the main navigation (left sidebar on Desktop).
2. On the **API credentials** page, click the **Create credential** button to the top-right.
3. Keep the **User type** on **Webservice**.
4. You may want to enter **Firmhouse** in the **Notes** field so in the future you know that this API user is used by Firmhouse.
5. On the right section add **[https://checkout.firmhouse.com](https://checkout.firmhouse.com)** to **Allowed origins**.
6. (Optional) If your Firmhouse project has a custom domain enabled, also enter the custom domain here. For example **[https://checkout.mycompany.com](https://checkout.mycompany.com)**.
7. To the bottom of the page under **Roles**, make sure that **Checkout webservice role**, **Checkout encrypted cardholder data**, **Data Protection API**, **Merchant PAL Webservice role**, and **Merchant Recurring role** are present and enabled. If one of these roles is not available, contact your account owner or Adyen support to enable the roles for your merchant.
8. Then under **Accounts**, enable the submerchant(s) that you want to connect to your **Firmhouse** project.
9. Click **Save**. The Web Service User is now created but we're not yet finished on this screen.
10. Under the **Authentication** section click **Generate New API Key**.
11. Store the generated API key somewhere safe or temporary. You will need to copy-paste it into the Firmhouse payment provider settings in later steps below.
12. Click **Save Generated API Key** to save the generated key for this user.
13. Keep the screen open in next steps so you can copy paste the **Client key** under **Authentication** in the steps below.

## In Adyen: Enable Merchant Account

When creating the API credentials, make sure that the Merchant Account that needs to be used for the transactions is enabled at the bottom of the page when creating/managing the credentials.

![Adyen Merchant Account settings](https://placehold.co/800x400?text=Adyen+Merchant+Account+Settings)

Otherwise, if you only enable certain sub-merchants, it could be the case that you do not have all the access rights you need.

## In Adyen: Create a Webhook for Your Merchant

The second thing we're going to create is a webhook pointing towards Firmhouse. The webhook ensures that checking out a new subscription works and that any payment statuses for (recurring) payments are automatically communicated back from Adyen to your Firmhouse project.

### Steps

1. First, make sure you are switched to a Merchant Account in your Adyen account. You can do this via the accounts dropdown which is the first element in the main navigation.
2. Now navigate to **Developers > Webhooks** in the main navigation.
3. On the **Webhooks** page click the **(+) Webhook** button.
4. In the **Standard notification** row, click the **Add** button.
5. Ensure the webhook is **Enabled**.
6. In the **URL** field enter **[https://portal.firmhouse.com/api/v1/payment\_status/adyen](https://portal.firmhouse.com/api/v1/payment_status/adyen)**
7. Make sure **Method** is set to **JSON**.
8. Expand the **Additional Settings** section and click **Generate new HMAC key**.
9. Store the generated HMAC that appears somewhere safe or temporary. You will need this when we're going to configure the payment provider settings in Firmhouse in the next steps below.
10. Click **Save Configuration** all the way down on the page, below the **Test Notifications** settings.

## In Adyen: Look Up Your API URL Prefix

The final thing to do is to look up the **API URL** prefix for your Adyen company account. This is also a configuration value you need to enter in the next steps in Firmhouse.

### Steps

1. In your Adyen account main navigation go to **Developers > API URLs**.
2. Note down or copy the first part of the URLs you see with format **\[hexadecimal number]-\[company name]**. For example: **9223d2d452babf3d-FirmhouseBV**. This value needs to be pasted into the Firmhouse settings in next steps.

## In Adyen: Verify "Capture Delay" Setting

There's a setting in your Adyen merchant settings called **Capture delay**. If **Capture delay** is set to **manual** then payments initiated via credit card are never **captured**. This means that the payment will stay open until you manually capture the payment via your Adyen account.

For this reason we advise to always set this setting to **immediate** unless you are sure you have other processes in place to capture payments. Setting capture delay to **immediate** will ensure that as soon as Firmhouse initiates a payment, the money will immediately be collected from your customer's credit card or bank account.

## In Firmhouse: Configure Adyen as Payment Provider

Now that we've finished the setup in Adyen, we can configure everything we've set up in your Firmhouse project and enable Adyen as payment provider on your project.

### Steps

1. In your Firmhouse project, go to **Settings > Payments** in the navigation.
2. If not already selected, select **Adyen** from the payment provider list.
3. Select your desired **Currency**.
4. Select the correct **Adyen environment**. Test for **ca-test** and Live for **ca-live**.
5. In the **Adyen API key** field, enter the key you generated, saved, and (temporarily) stored in steps 10-12 of the first section of this article.
6. In the **Adyen client key** field, enter the **Client key** of the Webservice User you created in the first section of this article (step 13).
7. Enter your merchant account name in the **Adyen merchant account** field.
8. In the **Adyen live url prefix** enter the value with the **\[hexadecimal number]-\[company name]** format. On the Adyen test environment, you need to enter your merchant account name here.
9. In the **Adyen webhook key (HMAC key)** field enter the value you obtained in section two of this article when creating the Adyen webhook.
10. Under **Payment methods**, select the payment methods you want to offer on Checkout and when your customers want to update their payment method. Depending on country, language, and currency certain payment methods might not appear on Checkout.

![Firmhouse Adyen settings](https://placehold.co/800x400?text=Firmhouse+Adyen+Payment+Settings)