Use API calls to configure terminals

Configure payment terminal settings using our Management API.

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.

Requirement	Description
Integration type	A point-of-sale integration with Adyen.
API credentials	You must have an API credential with an API key and the following roles: Management API—Terminal settings read Management API—Terminal settings read and write For sensitive terminal settings: Management API—Terminal Advanced settings read and write If you have a Terminal API integration with cloud-based communications, you can use the existing API key that you use for Terminal API requests.
Limitations	Note the following: See the list of terminal setting that are configurable using the Management API. Requests to live Management API endpoints related to terminal settings are subject to rate limits.

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.

Settings object	Description
deviceName	Custom name that is used to identify the terminal.
cardholderReceipt	Customize the header of the shopper receipt.
connectivity	`simcardStatus`: activate the SIM card in a specific payment terminal. This setting is only available at the terminal level.
gratuities	Enable tipping from the terminal, and predefine tipping options.
hardware	`displayMaximumBacklight`: set the brightness level of the terminal display.
offlineProcessing	Set the chip floor limit and offline swipe limit for offline EMV payments.
opi	For OPI integrations: enable Pay at Table and set the URL and store number for Pay at Table.
receiptOptions	Add your logo to the receipt. Specify data to print on the receipt as a QR code.
receiptPrinting	Determine whether the terminal should print a merchant receipt and/or a shopper receipt for certain transaction outcomes.
signature	Skip asking for a signature, considering that all global card schemes (American Express, China UnionPay, Diners, Discover, JCB, MasterCard, and Visa) regard a signature as optional. Or if you do not want to skip asking for a signature: determine whether you want the shopper to sign on the terminal display or on the receipt.
standalone	Set up the standalone feature and the default currency for payment terminals.
storeAndForward	Configure settings for store and forward offline payments.
surcharge	Configure passing on scheme fees as a surcharge.
tapToPay	Configure settings for Tap to Pay, for example the text shown on the screen of your mobile device. This setting is not available at the terminal level.
terminalInstructions	Configure the behaviour of the payment terminal, for example when the configuration update happens.
timeouts	Set the amount of time after which the terminal goes to sleep due to inactivity.
logos	Upload a logo to use as the terminal standby screen.

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

Settings object	Description
nexo	For local Terminal API integrations: specify event and display notifications URLs, and provide the key to secure local communications.
passcodes	Manage passcodes used to access payment terminal menus and features.
wifiProfiles	Provide properties of the Wi-Fi network the terminal should connect to. The terminal will connect to this network after boarding.

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:

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.
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:
When you receive the response, Base64-decode the data string to get the image file of the logo.
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:
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.

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

In the next sections we describe how to:

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

Update terminal logo

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.

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.

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:
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

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.
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

Shipped

Delivered

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