Search

Are you looking for test card numbers?

Would you like to contact support?

Developer-resource icon

API credentials

Authenticate the API requests that you make to Adyen.

Each API request that you make to Adyen is processed through an API credential linked to your company account. For an API request to be successful, you need to:

While most of our merchants only need a single API credential, you can also create multiple API credentials for increased security.

Generate an API key

To generate an API key, you need to have one of the following user roles:

  • Merchant admin role
  • Merchant system user management

To generate your API key:

  1. Log in to your Customer Area.
  2. Go to Account > API credentials, and select the credential for your integration, for example ws@Company.[YourCompanyAccount].
  3. Under Authentication, select Generate New API Key.
  4. Copy and securely store the API key in your system — you won't be able to restore it later.
    If your API key is lost or compromised, you need to generate a new one.
  5. Select Save at the bottom of the page.

When you switch to your live environment, you need to generate a new API key in your live Customer Area.

Changing your API key

When you generate a new API key, it can be used immediately. The old key will still work for 24 hours, allowing you to update your systems with the new key.

API permissions

The permissions of an API credential are managed by:

  • Assigning roles.
  • Restricting access to specific merchant accounts.

To change the permissions of an API credential:

  1. Log in to your Customer Area.
  2. Go to Account > API credentials, and select the API credential, for example ws@Company.[YourCompanyAccount].
  3. In the Roles and Associated Accounts pane:

    1. Select Roles, and use the toggles to assign roles.

    2. If you only want to use this credential for specific merchant accounts, select Account, and use the toggles to limit access to specific merchant accounts.

    Toggling the company account has the same effect as toggling all merchant accounts under that company account.

  4. Select Save at the bottom of the page.

Here is an overview of the most commonly used roles:

Role               Permissions
Merchant PAL webservice role                     Make API requests to Adyen.
If you disable this role, you can no longer process transactions with this API credential.
Checkout webservice role Use our Checkout API.
Pay by Link payments processing Create payment links.
Checkout encrypted cardholder data Use our Drop-in, Components, or Custom Card fields to send in encrypted card data.
API PCI Payments role Submit payment requests with raw card data.
For this role, you need to assess your PCI DSS compliance according to Self-Assessment Questionnaire D (SAQ D).
To enable this role, contact our Support Team.
Merchant Recurring role Use tokenization to save shopper's payment details and use them for future payments.
API Payment RefundWithData Submit unreferenced refunds.
To enable this role, contact our Support Team.
POS Terminal Management API role Use our Terminal Management API.

Multiple API credentials

When choosing whether to create multiple API credentials, there are trade-offs to consider. Having fewer credentials minimizes the number of API keys you need to handle, while having more gives you better control over API permissions, thereby increasing security. For example:

  • If you have both an online sales channel and an in-store sales channel, we strongly recommend creating a separate API credential for each channel.
  • If you're doing unreferenced refunds for online payments, we strongly recommend creating a separate credential for processing these refunds.
  • If you have an ecommerce system and a shipping system, you can separate the permissions for initiating and capturing payments.

Some merchants also choose to create separate API credentials for different legal entities or for different websites. These are just some considerations to take into account, and the amount of API credentials is ultimately up to you.

Create a new API credential

To be able to create new API credentials, you need to have one of the following user roles:

  • Merchant admin
  • Merchant system user management

To create a new credential:

  1. Log in to the Customer Area, and go to Account > API credentials.
    This opens a list with all API credentials linked to your company account.
  2. Select Add new credential.
  3. Under User type, select Webservice.
  4. In the Authentication pane, select Generate new API Key.
    This will generate an API key for the new API credential.
  5. Copy and securely store the API key in your system — you won't be able to restore it later.
  6. In the Roles and Associated Accounts pane,

    1. Select Roles, and use the toggles to assign roles to the new credential.

    2. If you only want to use this API credential for specific merchant accounts, select Account, and use the toggles to limit access to specific merchant accounts.

    Toggling the company account has the same effect as toggling all merchant accounts under that company account.

  7. Select Save at the bottom of the page.

(Optional) Basic authentication

If you're already using basic authentication to authenticate your API credentials, you can also set this up for the new credential:

  1. Log in to the Customer Area, and go to Account > API credentials.
  2. Add a new new credential, or select the credential for which you want to generate the password. This is usually called: ws@Company.[YourCompanyAccount].
  3. In the Authentication pane, in the Basic auth section:
    • If creating a new credential, copy the suggested password.
    • If changing the password of an existing credential, select Generate password, and copy the generated password.
  4. Securely store the password in your system — you won't be able to restore it later.
  5. Select Save at the bottom of the page.

Changing the basic auth password

Different from the API key, there is no overlap period when you can use both the old and the new basic authentication password.

If you generate a new basic authentication password, the old password stops working immediately.

Instead of generating a new password, you can create a new API credential. This will let you use both your existing password and a new one until you have updated your systems.

See also