Pesquisar

Are you looking for test card numbers?

Would you like to contact support?

Atenção, esta página não se encontra disponível em Português
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
  • Manage API credentials

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, select Roles, and use the toggles to assign roles.

  4. In the Roles and Associated Accounts pane, restrict access to specific merchant accounts. You have two ways to do that:

    1. Select Accounts, and use the toggles to assign specific merchant accounts.

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

    2. Select Account Groups, and use the toggles to assign account groups.
  5. Select Save at the bottom of the page.

Roles

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
  • Manage API credentials

To create a new credential:

  1. Log in to your 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. Go to the end of the page and select Save.
  5. In the Authentication pane, select Generate New API Key. This will generate an API key for the new API credential.
  6. Copy and securely store the API key in your system — you won't be able to restore it later.
  7. 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.

  8. Select Save at the bottom of the page.

(Optional) Set up basic authentication

If you're already using basic authentication to authenticate your API credentials, or if the API you're using requires basic authentication, you can set it up for a new or an existing credential:

  1. Log in to your Customer Area, and go to Account > API credentials.
  2. Add a 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