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.

API key and roles

To authenticate your requests to Management API, you need to 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, your API credential needs to have the following role:

• Management API—Terminal Advanced settings read and write

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, Diners, Discover, JCB, MasterCard, VISA, and UnionPay) regard a signature as optional. Or if you don't 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 can't 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 don't 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 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 don't 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 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 new passcodes when it makes a maintenance call to our systems. This happens automatically every 180 minutes. The new passcodes 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'll receive an email when this happens, and you can check your Terminal Order notifications. Or you can go to your Customer Area > Orders and returns and make sure that the order is Shipped or Delivered.

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

See also