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

These are the settings you can define using API calls:

Settings object Description
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.
Logo Upload a logo to use as the terminal standby screen.
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.

These settings are available under the following endpoints:

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

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.

Required roles

To use the Management API, your API credential must have the following roles:

  • Management API
  • View terminal TFM settings via API
  • Update terminal TFM settings via API

View current settings

To view the terminal configuration at a specific level:

  1. Retrieve the ID of the account, store, or terminal you want to see the settings for.

    Level Method Endpoint
    Company account GET https://management-test.adyen.com/v1/companies
    Merchant account GET https://management-test.adyen.com/v1/merchants
    Store GET https://management-test.adyen.com/v1/merchants/{merchantId}/stores
    Terminal GET https://management-test.adyen.com/v1/terminals

    For example, make a GET /merchants request:

    Get merchant ID
    curl https://management-test.adyen.com/v1/merchants \
    -H "x-API-key: YOUR_X-API-KEY" \
  2. When you receive the response, save the IDs for use in the URL of later requests:

    Level Endpoint
    Company account https://management-test.adyen.com/v1/companies/{companyId}
    Merchant account https://management-test.adyen.com/v1/merchants/{merchantId}
    Store https://management-test.adyen.com/v1/merchants/{merchantId}/stores/{storeId}
    Terminal https://management-test.adyen.com/v1/terminals/{uniqueTerminalId}

    In our example, the response returns an array with the merchant accounts that your API credential has access to.

    /merchants response
    {
      "data": [
        {
          "id": "MerchantPOSFrance",
          "name": "POS merchant account for France",
          "captureDelay": "120",
          "defaultShopperInteraction": "POS",
          "status": "Active",
          ...
        },
        {
          "id": "MerchantPOSGermany",
          "name": "POS merchant account for Germany",
          "captureDelay": "120",
          "defaultShopperInteraction": "POS",
          "status": "Active",
          ...
        }
      ]
      ...
    }
  3. 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.

    For example, to retrieve the logo for a specific terminal, make a GET  /terminals/{uniqueTerminalId}/terminalLogos} request.
    Or to retrieve the logo of a specific terminal model at the merchant account level, make a GET /merchants/{merchantId}/terminalLogos?model={model} request:

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

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

    For example, make a GET /merchants/{merchantId}/terminalSettings request:

    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",
            "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
        }
      },
      "gratuitySettings": [
        {
          "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"
      },
      "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
      }
    }

Update settings

Settings are parameters grouped in objects. When you define settings, you can make two types of changes:

  • Specify settings at a certain level.
  • Remove settings at a certain level. The parameters inherited from the next higher level will then apply.

For both changes you have to make a PATCH request. The request body only needs to contain the objects for the settings you want to specify or remove. Objects that are not included in the PATCH request will not be updated.

To specify a setting, you have to include the full object that contains the setting, even if you don't want to change all parameters in the object.

To remove a setting, you have to include the full object that contains the setting and specify an empty value for the parameter you no longer need. Or you can include the object with only the parameters you want to keep.

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, convert the logo image file to a Base64-encoded string.

  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.

    The request body should 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 change the logo for a specific terminal, make a PATCH /terminals/{uniqueTerminalId}/terminalLogos} request.
    Or to upload a new terminal logo for use in a store, make a PATCH /merchants/{merchantId}/stores/{storeId}/terminalLogos?model={model} request:

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

    1. Make sure you have the required certificates:

      • 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: EAP intermediate certificate in .pem format (optional).
      • For EAP-TLS: 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 other than the terminal logo, make a PATCH request to the /terminalSettings endpoint for the account, store, or terminal, specifying:

    • The full objects for the settings that you want to change.

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

    For example, let's assume you want to do 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.

    You'd make a PATCH merchants/{merchantId}/stores/{storeId}/terminalSettings request:

    Update store-level settings
    curl https://management-test.adyen.com/v1/merchants/{merchantId}/stores/{storeId}/terminalSettings \
    -H "x-API-key: YOUR_X-API-KEY" \
    -X PATCH \
    -d '{
         "gratuitySettings": [
           {
             "currency": "",
             "usePredefinedTipEntries": "",
             "predefinedTipEntries": [],
             "allowCustomAmount": ""
           }
         ],
         "signatureSettings": {
            "askSignatureOnScreen": "true",
            "skipSignature": "false"
          }
    }

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

When new settings take effect

Configuration changes take effect the next time that the terminal makes a maintenance call to our systems. This happens automatically, by default every 180 minutes. If you don't want to wait for this:

  1. Open the Admin menu.
  2. Select Config > Update.
    The terminal will retrieve the updated configuration and then restart.

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.

API reference for /terminalSettings

Below we describe the terminal setting you can configure through API calls to a /terminalSettings endpoint.

cardholderReceipt

The cardholderReceipt object lets you define the header of the shopper receipt.

Parameter Data type Description
headerForAuthorizedReceipt String Custom header to show on the shopper receipt for an authorised transaction. Allows one or two comma-separated header lines and blank lines. For example, "header,header,filler"

Required receipt content
You can safely add your own branding to a receipt, as described here. But be aware that you risk non-compliance when you modify the content of a receipt. Refer to Generate receipts.

gratuities

The gratuities array defines tipping from the terminal with or without predefined options to choose from. At levels where there can be multiple currencies, like the company level, the array can have an array item for each currency. At the terminal level, there will only be one array item.

Parameter Data type Description
currency String The currency that the tipping settings apply to.
usePredefinedTipEntries Boolean Indicates whether the terminal shows a prompt to enter a tip (false), or various tipping options to choose from (true).
preDefinedTipEntries Array Tipping options the shopper can choose from if usePredefinedTipEntries is true. The maximum number of predefined options is four, or three plus the option to enter a custom tip.
The array items can be a mix of:
  • A percentage of the transaction amount. Example: 5%
  • A tip amount in minor units. Example: 500 for a 5 EUR tip (if the currency is EUR)
allowCustomAmount Boolean Indicates whether one of the tipping options is to let the shopper enter a custom tip. It true, only three of the other options defined in predefinedTipEntry are shown.

nexo

The nexo object defines settings for a Terminal API integration.

Parameter Data type Description
nexoEventUrls Array (string) One or more URLs to send event messages to when using Terminal API.

opi

The opi object defines settings for an OPI integration.

Parameter Data type Description
enablePayAtTable Boolean Indicates if Pay at Table is enabled.
payAtTableStoreNumber" String The store number to use for Pay at Table.
payAtTableURL String The URL and port number used for Pay at Table communication.

signature

The signature object determines if and how the terminal prompts for a signature.

Parameter Data type Description
askSignatureOnScreen Boolean If skipSignature is false, indicates whether the shopper should provide a signature on the display (true) or on the merchant receipt (false).
skipSignature Boolean Skip asking for a signature. This is possible because all global card schemes (American Express, Diners, Discover, JCB, MasterCard, VISA, and UnionPay) regard a signature as optional.
deviceName String Name that identifies the terminal.

receiptOptions

The receiptOptions object lets you add a logo to the receipt.

Parameter Data type Description
logo String The receipt logo converted to a Base64-encoded string. The image must be a .bmp file of < 256 KB, dimensions 240 (H) x 384 (W) px.

receiptPrinting

The receiptPrinting object determines whether the terminal should print a merchant receipt and/or a shopper receipt for certain transaction outcomes.

Parameter Data type Description
merchantApproved Boolean Print a merchant receipt when the payment is approved.
merchantRefused Boolean Print a merchant receipt when the payment is refused.
merchantCancelled Boolean Print a merchant receipt when the payment is cancelled.
merchantRefundApproved Boolean Print a merchant receipt when the refund is approved.
merchantRefundRefused Boolean Print a merchant receipt when the refund is refused.
merchantCaptureApproved Boolean Print a merchant receipt when the payment is captured.
merchantCaptureRefused Boolean Print a merchant receipt when capturing the payment is refused.
merchantVoid Boolean Print a merchant receipt when a previous transaction is voided.
shopperApproved Boolean Print a shopper receipt when the payment is approved.
shopperRefused Boolean Print a shopper receipt when the payment is refused.
shopperCancelled Boolean Print a shopper receipt when the payment is cancelled.
shopperRefundApproved Boolean Print a shopper receipt when the refund is approved.
shopperRefundRefused Boolean Print a shopper receipt when the refund is refused.
shopperCaptureApproved Boolean Print a shopper receipt when the payment is captured.
shopperCaptureRefused Boolean Print a shopper receipt when capturing the payment is refused.
shopperVoid Boolean Print a shopper receipt when a previous transaction is voided.

wifiProfiles

The wifiProfiles object includes a profiles array for one or more Wi-Fi profiles, and a settings object with some general parameters.

Each profile (array item) in the profiles array should contain the required parameters and additional parameters depending on the profile type. This is the full list of parameters:

Parameter Data type Required Description
authType String -white_check_mark- The type of Wi-Fi network. Possible values: wpa-psk, wpa2-psk, wpa-eap, wpa2-eap.
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.
name String -white_check_mark- Your name for the Wi-Fi profile.
psk String For authType wpa-psk or wpa2-psk. The password to the wireless network.
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.
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.
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.
eap String For authType wpa-eap or wpa2-eap. Possible values: tls, peap, leap, fast
eapPwd String For eap peap. EAP-PEAP password from your MS-CHAP account. Must match the configuration of your RADIUS server.
eapIntermediateCert Object (file) For eap peap. The EAP intermediate certificate.
eapClientCert Object (file) For eap tls. The certificate chain for the terminals. All terminals in the same network will use the same EAP client certificate.
eapClientKey Object (file) For eap tls. The RSA private key for the client. Include the begin and end lines -----BEGIN RSA PRIVATE KEY----- and -----END RSA PRIVATE KEY-----
eapClientPwd String For eap tls. The password of the RSA key file, if that file is password-protected.

Above, the certificate file objects contain:

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 settings object contains:

Parameter Data type Description
band String Preferred Wi-Fi Band, for use if your terminal supports multiple bands. Possible values: All, 2.4GHz, 5GHz.
roaming Boolean Indicates whether roaming is enabled on the terminal. Only for VX680, VX690, VX820, and E355 terminals.
timeout Integer Time-out in seconds. Minimum value: 0

API reference for /terminalLogos

Below we describe the terminal setting you can configure through API calls to a /terminalLogos endpoint.

The following parameters specify the logo to be used as the standby screen on the terminal. You can only upload or remove one logo at a time.

Parameter Data type Description
model String The terminal model that the logo applies to. See below for the possible values.
image String The image file, converted to a Base-64 encoded string, of the logo to be shown on the terminal. Maximum length: 350000 characters.

To upload and remove a logo, you need to specify the terminal model as a query parameter. The allowed values for the model query parameter and the model parameter in the request body are as follows:

  • E355
  • E285
  • E285p
  • E280
  • MX925
  • UX300
  • UX301
  • UX410
  • VX680
  • VX690
  • VX820
  • P400Plus
  • V240m
  • V240mPlus
  • V200cPlus
  • V400cPlus
  • V400m
  • M400
  • S1E
  • S1F
  • S1F2
  • S1L
  • S7T
  • S1EL
  • S1U

See also