Adyen Payment Gateway Example

Summary #

This example explains how to configure an Adyen Direct payment gateway in LogiSense Billing. It covers the Adyen API credential, merchant accounts, payment methods, Standard webhook, LogiSense callback user, test and production gateway settings, and end-to-end validation.

Use separate Adyen and LogiSense configurations for test and production. Do not copy test API keys, webhook credentials, HMAC keys, merchant-account mappings, or payment methods into production.

For field-level information, see the Payment Gateway Screen guide. For current Adyen requirements, see Adyen’s website for API credentials, API credential roles, live endpoints, and webhook configuration.

Prerequisites #

Adyen Account and Merchant Accounts #

An Adyen test account is required for the test configuration.
An activated Adyen live account is required for the production configuration.
At least one active merchant account exists in each environment you configure.
The API credential has access to every merchant account that LogiSense Billing must use.
Required payment methods are enabled on each applicable merchant account and support the intended countries, currencies, and online-payments integration.
A user with the Manage API credentials or Merchant admin Customer Area role can create and configure the Adyen API credential.
A user with the Merchant admin or Merchant technical integrator Customer Area role can configure the Standard webhook.

LogiSense Billing #

A dedicated, enabled API-only LogiSense user and API-only role are available for Adyen Basic Authentication callbacks.
The LogiSense API endpoint is publicly reachable from Adyen over HTTPS. The callback route is:https://<logisense-api-host>/api/<api-version>/Webhook/Callback/Adyen
Firewalls, proxies, and load balancers allow Adyen to reach the callback endpoint and preserve the Authorization and User-Agent headers.
An account and payment test data are available for end-to-end validation.

Create the Adyen API Credential #

Create a separate credential in the test Customer Area and another credential in the live Customer Area.

Log in to the appropriate Adyen Customer Area and select the company account.
Navigate to Developers > API credentials.
Select the Payments tab.
Click Create new credential.
Select Web service user for the credential type.
Enter a description that identifies the LogiSense environment, such as LogiSense Billing - Test or LogiSense Billing - Production.
Create the credential and record its generated username in your credential inventory.
Under Server settings > Authentication, select the API key tab.
Click Generate API key.
Copy the API key immediately and store it in an approved secrets manager. Do not put the key in tickets, email, chat, source control, or this guide.
Configure the required roles and account scope described below.
Click Save changes.

When you generate a replacement API key, Adyen activates the new key immediately and keeps the previous key active for 24 hours. Update the corresponding LogiSense gateway and validate the connection within that rotation window. If necessary, Adyen also lets an authorized operator expire the previous key immediately or reset its remaining lifetime to 24 hours.

Required Roles and Permissions #

Enable the least-privilege roles required by this integration:

Adyen Role	Purpose in This Integration
Merchant PAL webservice role	Allows the credential to make payment API requests.
Checkout webservice role	Allows LogiSense Billing to create Adyen Checkout sessions.
Merchant Recurring role	Allows stored payment methods to be used for subsequent payments.
Management API—Account read	Allows LogiSense Billing to retrieve the merchant accounts visible to the credential.
Management API—Payment methods read	Allows LogiSense Billing to retrieve enabled payment-method settings for those merchant accounts.

The Management API—API credentials read and write and Management API—Webhooks read and write roles are not required when the API credential and webhook are managed manually in the Customer Area as described in this example.

Under the credential’s Accounts permissions, select the company account and all associated merchant accounts or explicitly select every merchant account that this LogiSense environment will use. A restricted credential can synchronize only the merchant accounts in its scope.

Configure Payment Methods in Adyen #

In the appropriate Adyen Customer Area, switch to the merchant account.
Navigate to Payments > Payment methods.
Request or add each payment method required by the implementation.
Complete any method-specific configuration and submit the request.
Confirm that each method is enabled for the merchant account before synchronizing it with LogiSense Billing.
Repeat these steps for every merchant account used by the environment.

Payment-method availability depends on the Adyen account, country, currency, shopper context, and integration. Enabling a method in Adyen does not guarantee that LogiSense Billing recognizes it.

LogiSense Billing contains mappings for the following Adyen method identifiers:

LogiSense Category	Recognized Methods or Brands
Credit Card	American Express, Diners, Discover, Mastercard, Visa, JCB, and Maestro
Direct Debit or Local Payment	ACH, BACS, GiroPay, iDEAL, Klarna Pay Now, Sofort, and SEPA
Wallet	PayPal, TWINT, and Vipps

The list is a recognition boundary, not a promise of availability. The saved gateway synchronizes enabled methods from Adyen, and LogiSense displays only merchant-account methods and card brands that it can map. Confirm the actual methods returned for each merchant account during validation.

Create the LogiSense Callback User #

Use a dedicated user for each environment. Do not reuse an interactive administrator or a callback user from another environment.

In LogiSense Billing, navigate to Setup > Users & Accounts > Users.
Click Add User.
Enter a unique User Name, such as adyen.webhook.test or adyen.webhook.production.
Enable API Only User.
Select a role configured as an API-only role.
Select Username / Password as the Authentication Type so Adyen can use the credential for webhook Basic Authentication.
Select Enabled as the User Status and complete the other required fields.
Save the user.
Set and securely store a strong password for the user using the approved LogiSense credential process.

Only enabled, non-interactive users appear in the gateway’s Callback User ID list. The selected user’s role must also be configured as API-only or the gateway callback settings will not save.

Configure the Adyen Standard Webhook #

Create a separate Standard webhook in the test and live Customer Areas. The gateway can be saved only after you have the webhook’s HMAC key and the LogiSense callback user.

Adyen generally recommends OAuth 2.0 for Standard webhooks, but the LogiSense Billing Adyen callback uses Basic Authentication with the dedicated API-only user described in this example. Protect that credential with HTTPS, HMAC validation, least privilege, and environment separation.

In the appropriate Adyen Customer Area, navigate to Developers > Webhooks.
Click Webhook, find Standard webhook, and click Add.
Enter a description that identifies the LogiSense environment.
Enable the webhook and select the applicable merchant accounts. Include only merchant accounts used by this LogiSense environment.
Under Server configuration, enter the environment’s LogiSense callback URL:https://<logisense-api-host>/api/<api-version>/Webhook/Callback/Adyen
Select JSON as the method and use HTTPS with TLS 1.2 or later.
Under Security > Basic authentication, enter the dedicated LogiSense API-only user’s User Name and password.
Under Security > HMAC Key, generate a new key.
Copy the HMAC key immediately to the environment’s secrets manager. You will enter the same value in the LogiSense gateway’s HMAC Key field.
Enable the events required by the payment workflow. LogiSense Billing processes the following mapped event codes:
- AUTHORISATION
- CAPTURE
- CAPTURE_FAILED
- REFUND
- REFUND_FAILED
- AUTORESCUE
- CANCEL_AUTORESCUE
- RECURRING_CONTRACT
- CHARGEBACK
Save the webhook configuration.

Adyen Standard webhooks normally send Adyen HttpClient 1.0 as the User-Agent. You can leave the LogiSense User Agent field blank to use that default. If the outbound webhook uses a different User-Agent, enter its exact value in LogiSense. LogiSense includes the User-Agent when matching a callback to its gateway settings, so a mismatch rejects the callback.

After the LogiSense gateway is active, use Adyen’s webhook test action. A successful callback returns HTTP 200 with [accepted]. Adyen retries webhook deliveries that are not acknowledged successfully within its required response window.

LogiSense Payment-Gateway Fields #

Navigate to Setup > Users & Accounts > Owners > Payment Gateways and click Add Payment Gateway.

Field	Definition
Name	Required name that identifies the environment-specific gateway.
Description	Optional description of the gateway and environment.
Active	Enables the gateway for processing. An active Adyen gateway is required for callback processing.
Gateway Type	Select Adyen Direct. This value becomes read-only after the gateway is saved. Do not select Adyen, which is the Spreedly-backed gateway type.
Capture Setting	Required capture behavior. It defaults to Automatic and becomes read-only after the gateway is saved. Choose the value required by the Adyen account’s capture configuration.
3DS2 Support	Enables 3DS2 behavior for the Adyen gateway when required.
Management URL	Required Adyen Management API base URL, including the API version. (LogiSense supports v1 of the Adyen API)
Test Gateway	Select for a test gateway. This clears and disables Production Prefix.
Production Prefix	Required when adding a production gateway. Enter only the prefix copied from Adyen, not a URL. It becomes read-only after the gateway is saved.
API Key	Required environment-specific Adyen API key. LogiSense validates it against Management URL when the gateway is saved.
Callback User ID	Required enabled API-only LogiSense user whose username and password are configured as the webhook’s Basic Authentication credentials.
User Agent	Optional input. Leave blank for the LogiSense default `Adyen HttpClient 1.0`, or enter the exact User-Agent sent by the webhook.
HMAC Key	Required key generated for the environment’s Adyen Standard webhook.

The Payment URL field is used by Spreedly gateways and is not displayed for Adyen Direct.

After the first save, the Merchant Accounts section becomes available:

Control	Definition
Pull Merchant Accounts	Synchronizes accessible merchant accounts and their enabled payment-method settings from Adyen. It is available only when the gateway has no unsaved changes.
Filter Merchant Account	Selects a synchronized merchant account so you can review its supported card types and filter the country grid.
Merchant Account	Maps the merchant account used for payments in a country.
Drop-in Merchant Account	Maps the merchant account used by Adyen Drop-in for a country.
Unassigned	Leaves that country without the corresponding merchant-account mapping.

Test Configuration Example #

Configure this example in a non-production LogiSense environment with credentials from the Adyen test Customer Area.

LogiSense Field	Sample Test Value
Name	`Adyen Direct - Test`
Description	`Adyen test environment`
Gateway Type	Adyen Direct
Capture Setting	Automatic, or the approved test capture behavior
3DS2 Support	Enabled when 3DS2 is in scope for testing
Management URL	`https://management-test.adyen.com/v3`
Test Gateway	Enabled
Production Prefix	Blank and disabled
API Key	Test API key stored in the secrets manager
Callback User ID	Dedicated test API-only user
User Agent	Blank to use `Adyen HttpClient 1.0`, unless the callback sends another value
HMAC Key	HMAC key from the test Standard webhook
Active	Enabled after all test values have been reviewed

Complete the fields using the test values and click Save. LogiSense validates the API key against the Management API before creating the gateway.
Reselect the saved gateway. The Merchant Accounts section is now visible.
With no pending changes, click Pull Merchant Accounts.
Confirm that the expected test merchant accounts are returned.
Select each merchant account in Filter Merchant Account and review the payment methods and card brands returned from Adyen.
For each applicable country, select the Merchant Account and Drop-in Merchant Account.
Save the gateway mappings.

Production Configuration Example #

Create this gateway in the production LogiSense environment only after the complete test checklist passes. Use credentials from the Adyen live Customer Area.

Locate the Production URL Prefix #

Log in to the live Adyen Customer Area.
Navigate to Developers > API URLs.
Locate Prefix.
Copy only the prefix value. For example, if Adyen displays 1797a841fbb37ca7-ExampleCompany, enter that exact string in LogiSense.

In Production Prefix, enter only the prefix you copied from Adyen, such as 1797a841fbb37ca7-ExampleCompany. Do not paste the full URL or add any other URL text. Check the prefix carefully before saving the gateway for the first time because you cannot edit it after the gateway is saved.

LogiSense Field	Sample Production Value
Name	`Adyen Direct - Production`
Description	`Adyen production environment`
Gateway Type	Adyen Direct
Capture Setting	Approved production capture behavior
3DS2 Support	Enabled when required by the production payment design
Management URL	`https://management-live.adyen.com/v3`
Test Gateway	Disabled
Production Prefix	Live prefix copied from Developers > API URLs > Prefix
API Key	Live API key stored in the production secrets manager
Callback User ID	Dedicated production API-only user
User Agent	Blank to use `Adyen HttpClient 1.0`, unless the callback sends another value
HMAC Key	HMAC key from the live Standard webhook
Active	Enabled after a production readiness review

Complete the production fields and compare them with the approved production credential record.
Confirm that Test Gateway is disabled and Production Prefix contains only the live prefix.
Click Save.
Reselect the gateway and click Pull Merchant Accounts.
Confirm that only the expected live merchant accounts are returned.
Configure the Merchant Account and Drop-in Merchant Account mappings for each production country.
Save the gateway mappings.

Use only one active Adyen Direct gateway for a LogiSense environment. Callback processing resolves the active Adyen gateway for the tenant; multiple active gateways can make callback association ambiguous.

Credential Security and Environment Separation #

Use separate API credentials, API keys, HMAC keys, webhook Basic Authentication users, passwords, merchant accounts, and callback URLs for test and production.
Use separate LogiSense API-only callback users for test and production.
Store all secrets in an approved secrets manager and restrict access to the payment-integration operators who require it.
Never place real secrets in documentation, source control, logs, screenshots, tickets, or sample configuration tables.
Limit the Adyen API credential’s account scope and roles to the merchant accounts and actions required by the integration.
Rotate API keys, callback passwords, and HMAC keys through a coordinated change. Update both ends of the integration and validate callbacks before retiring the previous credential.
When rotating an HMAC key, account for Adyen’s propagation period and follow Adyen’s current HMAC rotation guidance.
Do not clone a test gateway into production or convert a test configuration by replacing only its API key.

End-to-End Validation Checklist #

Complete the checklist in test before enabling the production gateway.

Gateway Creation and Merchant Accounts #

[ ] The gateway saves without an API-key or Management API error.
[ ] The gateway appears in Payment Gateways with Gateway Type set to Adyen Direct.
[ ] The saved gateway shows the expected test or production environment setting.
[ ] Pull Merchant Accounts returns every expected merchant account and no out-of-scope account.
[ ] Each applicable country has the correct Merchant Account and Drop-in Merchant Account mapping.
[ ] The expected payment methods and card brands are enabled in Adyen and visible where supported in LogiSense.

Payment and Webhook Receipt #

[ ] Create a payment using an Adyen test payment method and a supported country, currency, and merchant-account mapping.
[ ] Confirm that the payment and payment transaction appear on the LogiSense account with the expected status.
[ ] Confirm in Adyen that the authorization and capture behavior matches Capture Setting.
[ ] Use the Adyen Standard webhook test action and confirm HTTP 200 with [accepted].
[ ] Navigate to Operations > Monitor > Webhook Monitor, select Received, and confirm that the callback was received without an error.
[ ] Confirm that the relevant AUTHORISATION and, when applicable, CAPTURE webhook updates the existing LogiSense payment transaction.

Refund #

[ ] Refund a captured test payment from LogiSense Billing.
[ ] Confirm that Adyen accepts the refund request.
[ ] Confirm receipt of the REFUND webhook in Webhook Monitor > Received.
[ ] Confirm that the LogiSense payment and transaction reflect the refund.
[ ] Where practical, exercise a controlled failed scenario and confirm that CAPTURE_FAILED or REFUND_FAILED is received and recorded as expected.

Failure Troubleshooting #

[ ] For 401 Unauthorized, verify the webhook Basic Authentication username and password, and confirm the selected Callback User ID is enabled and API-only.
[ ] For API-key validation failures, verify that the key and Management URL belong to the same Adyen environment.
[ ] For 403 Forbidden or missing merchant accounts, verify the Management API roles and the API credential’s merchant-account scope.
[ ] If payment methods are missing, confirm they are enabled for the merchant account, valid for the country and currency, recognized by LogiSense Billing, and refreshed with Pull Merchant Accounts.
[ ] For rejected or repeatedly retried webhooks, compare the HMAC key, Basic Authentication credentials, callback URL, and exact User-Agent value on both sides.
[ ] Confirm that the Adyen gateway is active and that only the intended Adyen Direct gateway is active in the environment.
[ ] Review Operations > Monitor > Webhook Monitor > Received for the callback payload and error message, then correlate the Adyen PSP reference with the LogiSense payment transaction.
[ ] For production connection failures, verify Management URL, Production Prefix, DNS, outbound HTTPS access, and the live API key before changing any credentials.

Result #

The environment has an active Adyen Direct gateway with an environment-specific API key, Management API URL, callback user, webhook security settings, merchant-account mappings, and supported payment methods. Successful payment, webhook, and refund tests confirm that outbound payment requests and inbound Adyen events complete the expected LogiSense workflow.

Next Steps #

Configure the payment types that accounts will use. See Payment Types Example.
Add and test account payment methods. See Payments Example.
Review Adyen’s current webhook security recommendations before production launch.

Still stuck? How can we help?