Skip to main content
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 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.
  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. 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
  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. To limit Adyen’s country-aware result, select the payment methods you want to offer under Payment methods. Leave all methods unselected to let Adyen determine availability.

​
Offer different payment methods per country

Configure country-specific availability in your Adyen Customer Area. During checkout, Adyen first returns the methods available for the merchant account, country, currency, and amount. If you select payment methods in the Firmhouse payment provider configuration, Firmhouse limits the response to those methods. If you leave all methods unselected, Firmhouse does not add an account-level limit. The Firmhouse selection is an optional maximum list shared by every country assigned to the payment provider. It cannot make a method appear when Adyen does not return it for the checkout country. If you also need separate Firmhouse lists per country, create one Adyen payment provider configuration for each country or group of countries:
  1. Go to Settings > Payments.
  2. Create the additional Adyen payment provider configuration.
  3. Select the countries and payment methods for that configuration.
You can reuse the Adyen credentials when the configurations use the same merchant account. A country can only be assigned to one payment provider configuration.