Use API calls to configure terminals

The Management API lets you define payment terminal settings at various levels using API requests instead of the Customer Area.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

Configurable terminal settings

You can define terminal settings by making API requests to the following endpoints on a company, merchant, store, or terminal level:

• Terminal logos are under a dedicated /terminalLogos endpoint.
• The other settings are under a /terminalSettings endpoint.

Most settings from the following table link to the company account level as an example, but are also available on the other levels.

Sensitive terminal settings

Some terminal settings are considered sensitive because they can affect the Terminal API communications. Sensitive terminal settings are under a /terminalSettings endpoint on a company, merchant, store, or terminal level.

To authenticate your requests to these, you need to have the following role:

• Management API—Terminal Advanced settings read and write

If you need to define more settings, you have to go through the Customer Area.

Inheritance of settings

You can define terminal settings at different levels. From high to low:

• Company account level
• Merchant account level
• Store level
• Terminal level

The top level, above the company level, is the Adyen level. This is known as the PSP level. You cannot define settings at PSP level.

Settings at the company level apply to all terminals under the company. Settings at the merchant account level override settings inherited from the company level and apply to all terminals under the merchant account, and so on.

In other words: settings defined at a certain level propagate to all terminals at and under that level. But settings defined at a lower level replace values inherited from a higher level.

Get current settings

To view the terminal configuration at a specific level:

1. Get the ID of the account, store, or terminal you want to configure terminal settings for. You need to specify that ID in the URL of later requests.

   • For the company ID, make a GET /companies request.
   • For the merchant ID, make a GET /merchants request.
   • For the store ID, make a GET /stores request or a GET /merchants/{merchantId}/stores request.
   • For the terminal ID, make a GET /terminals request.

2. To retrieve the terminal logo, make a GET request to the /terminalLogos endpoint for the account, store, or terminal. You can retrieve only one logo at a time. On the account or store level, you need to specify the terminal model as a query parameter. On the terminal level no model query parameter is needed because we can infer the model from the terminal ID in the URL.

   Use the following endpoints:

   • GET /companies/{companyId}/terminalLogos?model={model}
   • GET /merchants/{merchantId}/terminalLogos?model={model}
   • GET /stores/{storeId}/terminalLogos?model={model}
   • GET /terminals/{terminalId}/terminalLogos

3. When you receive the response, Base64-decode the data string to get the image file of the logo.

4. To retrieve the other terminal settings (except the logo), make a GET request to the /terminalSettings endpoint for the account, store, or terminal.

   Use the following endpoints:

   • GET /companies/{companyId}/terminalSettings
   • GET /merchants/{merchantId}/terminalSettings
   • GET /stores/{storeId}/terminalSettings
   • GET /terminals/{terminalId}/terminalSettings

   The response returns the current configuration.

Update settings

Settings are parameters grouped in objects.

• To change a parameter value, include the full object that contains the parameter, even if you do not want to change all parameters in the object.
• To remove a parameter value at a certain level and restore the value inherited from the next higher level, include the full object that contains the parameter, and specify an empty value for the parameter or omit the parameter.
• Objects that are not included in the request are not updated.

In the next sections we describe how to:

• Specify or remove a terminal logo
• Specify or remove other terminal settings

Update terminal logo

1. Make sure that you know:

   • The level where you need to add or remove a logo to get the desired effect.
   • The current logo at that level. When removing a logo, you also need to know the logo that will be inherited from the next higher level.

   • The terminal model that you want to change the logo for.

2. For a new logo, make sure the file matches the logo requirements for the terminal model, and convert the file to a Base64-encoded string.

   model	Logo dimensions width x height	File size	Supports GIF BMP JPG JPEG PNG
   AMS1	480 x 800	Max. 1 MB	GIF and PNG
   E280	320 x 444	Max. 512 KB
   E285	240 x 284	Max. 512 KB
   E285p	240 x 284	Max. 512 KB
   E355	320 x 150	Validation on WxH
   M400	854 x 432	Max. 512 KB
   MX925	800 x 443	Max. 500 KB
   P400Plus	320 x 450	Max. 512 KB
   S1E	720 x 1280	Max. 1 MB
   S1E2	720 x 1280	Max. 1 MB
   S1E2L	720 x 1280	Max. 1 MB
   S1EL	720 x 1280	Max. 1 MB
   S1F2	720 x 1280	Max. 1 MB
   S1F2L	720 x 1280	Max. 1 MB
   S1U	720 x 1280	Max. 1 MB
   V200cPlus	-	-	-
   V240m	320 x 450	Max. 512 KB
   V240mPlus	320 x 450	Max. 512 KB
   V400cPlus	320 x 450	Max. 512 KB
   V400m	320 x 450	Max. 512 KB
   VX680	240 x 200	Validation on WxH
   VX690	240 x 200	Validation on WxH
   VX820	240 x 200	Validation on WxH
   UX300	128 x 42	Validation on WxH
   UX301	128 x 42	Validation on WxH
   UX410	128 x 42	Validation on WxH

   If the dimensions of the logo do not match the requirements:

   • BMP, JPG, JPEG, or PNG files are resized.
   • A GIF file is converted to a single-frame image.

3. Make a PATCH request to the /terminalLogos endpoint for the account, store, or terminal. You can update only one logo at a time. On the account or store level, you need to specify the terminal model as a query parameter. On the terminal level no model query parameter is needed because we can infer the model from the terminal ID in the URL.

   Use the following endpoints:

   • PATCH /companies/{companyId}/terminalLogos?model={model}
   • PATCH /merchants/{merchantId}/terminalLogos?model={model}
   • PATCH /stores/{storeId}/terminalLogos?model={model}
   • PATCH /terminals/{terminalId}/terminalLogos

   The request body must contain:

   • data: to upload a logo, specify the Base64-encoded string of the logo file. To remove a logo, specify an empty string.

   For example, to upload a new terminal logo for use in a store:

   The response returns the logo data at the level where you made the request.

   When you remove a terminal logo, the terminal inherits a logo from a higher level and the response returns that other logo. For example, let's assume you changed your mind and want to replace the store logo you just added with the logo defined at the merchant account level. You'd make a PATCH merchants/{merchantId}/stores/{storeId}/terminalLogos?model={model} request:

   The response returns the logo inherited from a higher level:

Update other settings

1. Make sure that you know:

   • The level where you need to add or remove settings to get the desired effect.

   • The current settings at that level. When removing settings, you also need to know the settings that will be inherited from the next higher level.

2. To update settings (except the terminal logo), make a PATCH request to the /terminalSettings endpoint for the account, store, or terminal.

   Use the following endpoints:

   • PATCH /companies/{companyId}/terminalSettings
   • PATCH /merchants/{merchantId}/terminalSettings
   • PATCH /stores/{storeId}/terminalSettings
   • PATCH /terminals/{terminalId}/terminalSettings

   In the request body, specify the full objects for the settings that you want to change.

   If you omit a parameter from an object, that setting is removed.

   Remote Wi-Fi profiles require many different parameters depending on the type or of network: Enterprise EAP-PEAP, Enterprise EAP-TLS, or Personal PSK. For details, see Set up Wi-Fi profiles using API calls.

   The next example shows a request that does two things:

   • You previously defined tipping settings for a store but now want to remove those and go back to the tipping settings from the merchant level.
   • You want to change the skipSignature setting for the store from true to false.

   The response returns the entire configuration at the level where you made the request.

When new settings take effect

The terminal downloads the configuration changes when it makes a maintenance call to our systems. This happens automatically every 180 minutes. The configuration changes then take effect when the terminal restarts. This happens automatically at the restart hour, which is usually set to 6:00 AM.

To switch to the new passcode immediately, update the configuration on your terminal manually:

• Go to Settings > Configuration, enter your Admin & Settings passcode and select Update.

• For non-Android terminals that use the old menu structure: go to the Admin menu and select Config > Update.

The terminal downloads the updated configuration and then restarts.

If you ordered new terminals and want to update the settings at terminal level, you can configure the new terminals as soon as they are shipped. You receive an email when this happens, and you can check your Terminal order update webhooks. Or you can go to your Customer Area > Orders and returns and make sure that the order is

On new terminals, the settings take effect when the terminal is boarded.

See also