Are you looking for test card numbers?

Would you like to contact support?

Point-of-sale icon

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.

This feature is in the development phase. The API, documentation, and processes will change as the feature evolves. If you have any feedback on the feature, reach out to your Adyen contact.

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.
gratuities Enable tipping from the terminal, and predefine tipping options.
nexo For local Terminal API integrations: specify event notification URLs.
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.
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: whether you want the shopper to sign on the terminal display or on the receipt.
wifiProfiles Provide properties of the Wi-Fi network the terminal should connect to. The terminal will connect to this network after boarding.
timeouts Set the amount of time after which the terminal goes to sleep due to inactivity.
hardware displayMaximumBacklight: set the brightness level of the terminal display.
connectivity simcardStatus: activate the SIM card in a specific payment terminal. This setting is only available at the terminal level.
surcharge Configure passing on scheme fees as a surcharge.
logos Upload a logo to use as the terminal standby screen.

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.

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

If you are using a Terminal API integration with cloud-based communications, you can use the existing API key that you use for Terminal API requests.

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.

    Get merchant ID
    curl https://management-test.adyen.com/v1/merchants \
    -H "x-API-key: YOUR_X-API-KEY" \
  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 merchant-level logo for V400m terminal
    curl https://management-test.adyen.com/v1/merchants/{merchantId}/terminalLogos?model=V400m \
    -H "x-API-key: YOUR_X-API-KEY" \
  3. When you receive the response, Base64-decode the data string to get the image file of the logo.

    Response showing current logo
    {
      "data": "R0lGODlh...AAAcDgH+BADs="
    }
  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 merchant-level terminal settings
    curl https://management-test.adyen.com/v1/merchants/{merchantId}/terminalSettings \
    -H "x-API-key: YOUR_X-API-KEY" \

    The response returns the current configuration.

    Response showing current settings
    {
      "wifiProfiles": {
        "profiles": [
          {
            "authType": "wpa-eap",
            "autoWifi": "false",
            "bssType": "infra",
            "channel": 0,
            "defaultProfile": true,
            "hiddenSsid": false,
            "name": "YOUR_PROFILE",
            "psk": "NETWORK_PASSWORD",
            "ssid": "NETWORK_SSID",
            "wsec": "tkip",
            "eapIdentity": "store1234",
            "eapCaCert": {
              "name": "ca.pem",
              "data": "...base64..."
            },
            "eap": "tls",
            "eapClientCert": {
              "name": "client.pem",
              "data": "...base64..."
            },
            "eapClientKey": {
              "name": "key.pem",
              "data": "...base64..."
            },
            "eapClientPwd": "123456789"
          },
          {
            "authType": "wpa-psk",
            "autoWifi": false,
            "bssType": "adhoc",
            "channel": 11,
            "defaultProfile": false,
            "name": "YOUR_SECONDARY_PROFILE",
            "psk": "NETWORK_PASSWORD",
            "ssid": "NETWORK_SSID",
            "wsec": "tkip"
          }
        ],
        "settings": {
          "band": "All",
          "roaming": true,
          "timeout": 20
        }
      },
      "gratuities": [
        {
          "currency": "EUR",
          "usePredefinedTipEntries": true,
          "predefinedTipEntries": [
            "5%",
            "10%",
            "500"
          ],
          "allowCustomAmount":true
        }
      ],
      "nexoSettings": {
        "nexoEventUrls": [
          "http://your.event.url.1",
          "http://your.event.url.2",
          "http://your.event.url.3"
        ]
      },
      "opiSettings": {
        "enablePayAtTable": true,
        "payAtTableStoreNumber": "42",
        "payAtTableURL": "http://your.payattable.url"
      },
      "signatureSettings": {
        "askSignatureOnScreen": true,
        "skipSignature": true,
        "deviceName": "Paris1-12"
    
      },
      "receiptSettings": {
        "merchantApproved": true,
        "merchantRefused": false,
        "merchantCancelled": false,
        "merchantRefundApproved": true,
        "merchantRefundRefused": false,
        "merchantCaptureApproved": false,
        "merchantCaptureRefused": false,
        "merchantVoid": true,
        "shopperApproved": true,
        "shopperRefused": true,
        "shopperCancelled": true,
        "shopperRefundApproved": true,
        "shopperRefundRefused": true,
        "shopperCaptureApproved": false,
        "shopperCaptureRefused": false,
        "shopperVoid": false
      },
      "timeouts": {
        "fromActiveToSleep": 30
      },
      "hardware": {
        "displayMaximumBackLight": 75
      },
      "connectivity": {
        "simcardStatus": "INVENTORY"
      }
    }

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.

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

In the next sections we describe how to:

  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
    E280 320 x 444 Max. 512 KB -white_check_mark-
    E285 240 x 284 Max. 512 KB -white_check_mark-
    E285p 240 x 284 Max. 512 KB -white_check_mark-
    E355 320 x 150 Validation on WxH -white_check_mark-
    M400 854 x 432 Max. 512 KB -white_check_mark-
    MX925 800 x 443 Max. 500 KB -white_check_mark-
    P400Plus 320 x 450 Max. 512 KB -white_check_mark-
    S1E 720 x 1280 Max. 1 MB -white_check_mark-
    S1E2 720 x 1280 Max. 1 MB -white_check_mark-
    S1E2L 720 x 1280 Max. 1 MB -white_check_mark-
    S1EL 720 x 1280 Max. 1 MB -white_check_mark-
    S1F - - -
    S1F2 720 x 1280 Max. 1 MB -white_check_mark-
    S1F2L 480 x 800 Max. 1 MB -white_check_mark-
    S1L - - -
    S1U 720 x 1280 Max. 1 MB -white_check_mark-
    S7T - - -
    V200cPlus - - -
    V240m 320 x 450 Max. 512 KB -white_check_mark-
    V240mPlus 320 x 450 Max. 512 KB -white_check_mark-
    V400cPlus 320 x 450 Max. 512 KB -white_check_mark-
    V400m 320 x 450 Max. 512 KB -white_check_mark-
    VX680 240 x 200 Validation on WxH -white_check_mark-
    VX690 240 x 200 Validation on WxH -white_check_mark-
    VX820 240 x 200 Validation on WxH -white_check_mark-
    UX300 128 x 42 Validation on WxH -white_check_mark-
    UX301 128 x 42 Validation on WxH -white_check_mark-
    UX410 128 x 42 Validation on WxH -white_check_mark-

    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:

    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:

    Upload new store-level logo
    curl https://management-test.adyen.com/v1/stores/{storeId}/terminalLogos?model=V400m \
    -H "x-API-key: YOUR_X-API-KEY" \
    -X PATCH \
    -d '{
         "data": "Z3lFPDxt...AAAcDgH+BADs="
    }

    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:

    Remove store-level logo
    curl https://management-test.adyen.com/v1/stores/{storeId}/terminalLogos?model=V400m \
    -H "x-API-key: YOUR_X-API-KEY" \
    -X PATCH \
    -d '{
         "data": ""
    }

    The response returns the logo inherited from a higher level:

    Response showing current logo
    {
      "data": "R0lGODlh...AAAcDgH+BADs="
    }

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. For a new Enterprise EAP-PEAP or EAP-TLS Wi-Fi profile:

    1. Make sure you have the required certificates:

      • The CA root certificate in .pem format. This must be the root certificate from the CA that signed the certificate of the RADIUS server that is part of your wireless network.
      • For EAP-PEAP: the EAP intermediate certificate in .pem format (optional).
      • For EAP-TLS: the client certificate for the terminals in .pem format and the client key in .pem or .key format.

    2. Convert each certificate file to a Base64-encoded string.

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

    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.

      For Wi-Fi profiles, you need specify general network settings and specific parameters for each profile in the profiles array. For the parameters of different types of profiles, see the table below.

    For an Enterprise EAP-PEAP Wi-Fi profile, use the following parameters:

    Parameter Data type Required Description
    authType String -white_check_mark- The type of Wi-Fi network. Use the value wpa-eap for a WPA Enterprise network, or wpa2-eap for a WPA2 Enterprise network.
    autoWifi Boolean Indicates whether to automatically select the best authentication method available. Does not work on older terminal models.
    bssType String -white_check_mark- Use infra for infrastructure-based networks. This applies to most networks. Use adhoc only if the communication is p2p-based between base stations.
    channel Integer Channel number of the Wi-Fi network. The recommended setting is 0 for automatic channel selection.
    defaultProfile Boolean Indicates whether this is your preferred wireless network. If true, the terminal will try connecting to this network first.
    eap String For authType wpa-eap or wpa2-eap. Use the value peap. (Other possible values: tls, leap, fast.)
    eapCaCert Object (file) For authType wpa-eap or wpa2-eap. The root certificate from the CA that signed the certificate of the RADIUS server that is part of your wireless network.
    eapIdentity String For authType wpa-eap or wpa2-eap. EAP-PEAP username from your MS-CHAP account. Must match the configuration of your RADIUS server.
    eapIntermediateCert Object (file) For eap peap. The EAP intermediate certificate.
    eapPwd String For eap peap. EAP-PEAP password from your MS-CHAP account. Must match the configuration of your RADIUS server.
    hiddenSsid Boolean Indicates if a network doesn't broadcast its SSID. Mandatory for Android terminals, because these terminals rely on this setting to be able to connect to any network.
    name String -white_check_mark- Your name for the Wi-Fi profile.
    ssid String -white_check_mark- The name of the wireless network.
    wsec String -white_check_mark- The type of encryption. Possible values: auto, ccmp (recommended), tkip.

    The certificate file objects (eapCaCert and eapIntermediateCert) each consist of:

    Parameter Data type Description
    name String Name of the certificate. Must be unique across Wi-Fi profiles.
    data String Certificate content converted to a Base64-encoded string.

    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.
    Update store-level settings
    curl https://management-test.adyen.com/v1/stores/{storeId}/terminalSettings \
    -H "x-API-key: YOUR_X-API-KEY" \
    -X PATCH \
    -d '{
         "gratuities": [
           {
             "currency": "",
             "usePredefinedTipEntries": "",
             "predefinedTipEntries": [],
             "allowCustomAmount": ""
           }
         ],
         "signatureSettings": {
            "askSignatureOnScreen": true,
            "skipSignature": false,
            "deviceName": "Paris1-12"
          }
    }

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

When new settings take effect

The terminal downloads 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. If you don't want to wait for this:

  1. Open the Admin menu.
  2. 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