Payment Provider Adyen

Connect Adyen to instellix to charge customers, receive payment status updates, and import settlement reports for accounting and payment assignment.

This article covers the Adyen setup in Adyen and in the instellix webportal. For automatic retries after failed charges, see Payment Retry Configuration.

Requirements

• An Adyen company / merchant account
• Access to Adyen Developers (API credentials and webhooks) and Reports
• Permission to configure Integration > Payment Providers in instellix
• A Merchant Payment Account and Merchant Payment Gateway for Adyen

Multiple Adyen configurations

A tenant can have several Adyen configurations. Use separate configurations when you operate different Adyen merchant accounts within one instellix tenant, for example for different business models, entities, or currency setups.
Each configuration has its own:

• Name in instellix
• Adyen merchant account
• instellix Merchant Payment Account
• Charging and report API credentials
• Webhook configuration
• Authorization mode and retry settings
  Go to: Integration > Payment Providers > Adyen
  Click Add in the Adyen panel for every merchant account you want to connect. Use a descriptive configuration name, for example Adyen B2C EUR.

An Adyen configuration and an instellix Merchant Payment Account are different objects. The Adyen configuration stores the provider connection and credentials. The Merchant Payment Account controls how instellix routes and processes payment operations. Select the relevant Merchant Payment Account in each Adyen configuration.
Complete the following setup for each Adyen configuration.

Setup overview

---

1. Charging credentials (Web Service User)

In Adyen

1. Go to Developers > API credentials.
2. Create new credentials of type Web Service User.
3. Generate and copy the API key.

In instellix

Go to: Integration > Payment Providers > Adyen

1. Add or edit the relevant Adyen configuration.
2. Enter a descriptive configuration name.
3. Enter the Web Service User API key.
4. Enter the Adyen merchant account name. Do not enter a username such as ws@....
5. Select the related instellix Merchant Payment Account.
6. For production, enter the live URL prefix only, not the full URL.
   In Adyen, you find the prefix under Developers > API URLs. The checkout URL follows this pattern:
   https://[prefix]-checkout-live.adyenpayments.com/checkout/v{version}/{method}
   Enter only the [prefix] part. On stage or test environments, leave the live URL prefix empty.
7. Save the configuration.

---

2. Webhook configuration

Webhooks allow instellix to receive payment intent updates and settlement-related events from Adyen.

In Adyen

1. Go to Developers > Webhooks.
2. Create a new webhook (typically Standard webhook).
3. Under HMAC, generate a new HMAC key and copy it.

In instellix

Go to: Integration > Payment Providers > Adyen

1. Open Webhook Configuration.
2. Paste the Adyen HMAC key and save.
3. instellix shows a username and password.
   Copy the password immediately — it is shown only once (you can regenerate later if needed).

Back in Adyen

1. Enter the instellix webhook username and password on the Adyen webhook.
2. Save the webhook.
3. Optionally use Test Configuration in Adyen to send a test message to instellix.

After this, webhooks are received for payment intents and settlement reports.

---

3. Settlement reports

So that Adyen settlement data can be processed in instellix, configure reporting in both systems.

In Adyen

1. Create API credentials of type Report Service User (Developers > API credentials) and copy the API key.
2. Go to Reports > Settlement Details.
3. Enable Generate > Automated (typically Daily).

In instellix

Go to: Integration > Payment Providers > Adyen

1. Open the relevant Adyen configuration.
2. Enter the Report API key.
3. Select / enter the related Adyen Merchant Payment Account.
4. Save.

Journal types processed by instellix

instellix processes the following Adyen settlement journal types from the Settlement Details report:

Balancetransfer rows are ignored (informational only; no settlement item is created).

Chargeback-related fees from the report (e.g. commission on chargeback lines) are mapped into the settlement item fee structure where applicable.

---

4. Merchant Payment Account and Gateway

1. Create a Merchant Payment Account with payment provider Adyen:
   Configuration > Payment > Merchant Payment Account
2. Create a Merchant Payment Gateway and attach that account (per currency as needed):
   Configuration > Payment > Merchant Payment Gateways

Learn more: Merchant Payment Accounts · Merchant Payment Gateways

---

5. Customer Payment Accounts (CPA)

For charging, each customer needs a Customer Payment Account that references the tokenized payment method in Adyen.

Typical mapping:

Also select the Adyen Merchant Payment Gateway on the CPA.

Learn more: Customer Payment Accounts

---

6. Retry Strategy

Under Integration > Payment Providers > Adyen, configure the Retry Strategy for recoverable failed charges (Retry Type, Retry Value, Max Retry Attempts).

Configure retry settings separately for each Adyen configuration.

See Payment Retry Configuration — including the Day-of-month rule.

---

Related articles

• Payment Providers
• Payment Retry Configuration
• Payment Management
• Payment Terms