Get terminal settings

get/merchants/{merchantId}/terminalSettings

API Version

Returns the payment terminal settings that are configured for the merchant account identified in the path. These settings apply to all terminals under the merchant account unless different values are configured at a lower level (store or individual terminal).

To make this request, your API credential must have one of the following roles:

Management API—Terminal settings read
Management API—Terminal settings read and write

For sensitive terminal settings, your API credential must have the following role:

Management API—Terminal settings Advanced read and write

In the live environment, requests to this endpoint are subject to rate limits.

Endpoint destination URL

https://management-test.adyen.com/v3/merchants/{merchantId}/terminalSettings

Path Parameters

Required

Optional

The unique identifier of the merchant account.

Response parameters

After submitting a call, you receive a response message to inform you that your request was received and processed.

Depending on the HTTP status code of the response message, it is helpful to build some logic to handle any errors that a request or the system may return.

HTTP Responses

200 - OK
The request has succeeded.
cardholderReceiptobject
Settings to define the header of the shopper receipt.
headerForAuthorizedReceiptstring
A 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
connectivityobject
Settings for terminal connectivity features.
simcardStatusstring
Indicates the status of the SIM card in the payment terminal. Can be updated and received only at terminal level, and only for models that support cellular connectivity.

Possible values:

ACTIVATED: the SIM card is activated. Cellular connectivity may still need to be enabled on the terminal itself, in the Network settings.

INVENTORY: the SIM card is not activated. The terminal can't use cellular connectivity.

terminalIPAddressURLobject
The list of local and public URLs to send notifications to when using local integrations.
eventLocalUrlsarray[object]
One or more local URLs to send event notifications to when using Terminal API.
encryptedboolean
Indicates if the message sent to this URL should be encrypted.
passwordstring
The password for authentication of the notifications.
urlstring
The URL in the format: http(s)://domain.com.
usernamestring
The username for authentication of the notifications.
eventPublicUrlsarray[object]
One or more public URLs to send event notifications to when using Terminal API.
encryptedboolean
Indicates if the message sent to this URL should be encrypted.
passwordstring
The password for authentication of the notifications.
urlstring
The URL in the format: http(s)://domain.com.
usernamestring
The username for authentication of the notifications.
gratuitiesarray[object]
Settings for tipping with or without predefined options to choose from. The maximum number of predefined options is four, or three plus the option to enter a custom tip.
allowCustomAmountboolean
Indicates whether one of the predefined tipping options is to let the shopper enter a custom tip. If true, only three of the other options defined in predefinedTipEntries are shown.
currencystring
The currency that the tipping settings apply to.
predefinedTipEntriesarray[string]
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 options can be a mix of:

A percentage of the transaction amount. Example: 5%

A tip amount in minor units. Example: 500 for a EUR 5 tip.

usePredefinedTipEntriesboolean
Indicates whether the terminal shows a prompt to enter a tip (false), or predefined tipping options to choose from (true).
hardwareobject
Settings for terminal hardware features.
displayMaximumBackLightinteger
The brightness of the display when the terminal is being used, expressed as a percentage.
resetTotalsHourinteger
The hour of the day when the terminal is set to reset the Totals report. By default, the reset hour is at 6:00 AM in the timezone of the terminal. Minimum value: 0, maximum value: 23.
restartHourinteger
The hour of the day when the terminal is set to reboot to apply the configuration and software updates. By default, the restart hour is at 6:00 AM in the timezone of the terminal. Minimum value: 0, maximum value: 23.
localizationobject
Settings for localization.
languagestring
Language of the terminal.
secondaryLanguagestring
Secondary language of the terminal.
timezonestring
The time zone of the terminal.
nexoobject
Settings for a Terminal API integration.
displayUrlsobject
The list of local and public URLs to send display notifications to when using Terminal API.
localUrlsarray[object]
One or more local URLs to send notifications to when using Terminal API.
encryptedboolean
Indicates if the message sent to this URL should be encrypted.
passwordstring
The password for authentication of the notifications.
urlstring
The URL in the format: http(s)://domain.com.
usernamestring
The username for authentication of the notifications.
publicUrlsarray[object]
One or more public URLs to send notifications to when using Terminal API.
encryptedboolean
Indicates if the message sent to this URL should be encrypted.
passwordstring
The password for authentication of the notifications.
urlstring
The URL in the format: http(s)://domain.com.
usernamestring
The username for authentication of the notifications.
encryptionKeyobject
The key you share with Adyen to secure local communications when using Terminal API.
identifierstring
The unique identifier of the shared key.
passphrasestring
The secure passphrase to protect the shared key. Must consist of:

At least 12 characters.

At least 1 uppercase letter: [A-Z].

At least 1 lowercase letter: [a-z].

At least 1 digit: [0-9].

At least 1 special character. Limited to the following: ~, @, $, %, ^, &, *, (, ), _, +, =, }, {, ], [, ;, :, ?, ., ,, >, <.

versioninteger
The version number of the shared key.
eventUrlsobject
The list of local and public URLs to send event notifications to when using Terminal API.
eventLocalUrlsarray[object]
One or more local URLs to send event notifications to when using Terminal API.
encryptedboolean
Indicates if the message sent to this URL should be encrypted.
passwordstring
The password for authentication of the notifications.
urlstring
The URL in the format: http(s)://domain.com.
usernamestring
The username for authentication of the notifications.
eventPublicUrlsarray[object]
One or more public URLs to send event notifications to when using Terminal API.
encryptedboolean
Indicates if the message sent to this URL should be encrypted.
passwordstring
The password for authentication of the notifications.
urlstring
The URL in the format: http(s)://domain.com.
usernamestring
The username for authentication of the notifications.
nexoEventUrlsarray[string]Deprecated in version 1
Use eventUrls instead.
One or more URLs to send event messages to when using Terminal API.
notificationobject
Configures sending event notifications by pressing a button on a terminal, for example used for pay-at-table.
categorystring
The type of event notification sent when you select the notification button.
detailsstring
The text shown in the prompt which opens when you select the notification button. For example, the description of the input box for pay-at-table.
enabledboolean
Enables sending event notifications either by pressing the Confirm key on terminals with a keypad or by tapping the event notification button on the terminal screen.
showButtonboolean
Shows or hides the event notification button on the screen of terminal models that have a keypad.
titlestring
The name of the notification button on the terminal screen.
offlineProcessingobject
Settings for offline payment features.
chipFloorLimitinteger
The maximum offline transaction amount for chip cards, in the processing currency and specified in minor units.
offlineSwipeLimitsarray[object]
The maximum offline transaction amount for swiped cards, in the specified currency.
amountinteger
The transaction amount, in minor units.
currencyCodestring
The three-character ISO currency code.
opiobject
Settings for an Oracle Payment Interface (OPI) integration.
enablePayAtTableboolean
Indicates if Pay at table is enabled.
payAtTableStoreNumberstring
The store number to use for Pay at Table.
payAtTableURLstring
The URL and port number used for Pay at Table communication.
passcodesobject
Settings for passcodes features.
adminMenuPinstring
Max length: 6
The passcode for the Admin menu and the Settings menu.
refundPinstring
Max length: 6
The passcode for referenced and unreferenced refunds on standalone terminals.
screenLockPinstring
Min length: 4Max length: 6
The passcode to unlock the terminal screen after a timeout.
txMenuPinstring
Max length: 6
The passcode for the Transactions menu.
payAtTableobject
Settings for Pay-at-table features.
authenticationMethodstring
Allowed authentication methods: Magswipe, Manual Entry.
enablePayAtTableboolean
Enable Pay at table.
paymentInstrumentstring
Sets the allowed payment instrument for Pay at table transactions. Can be: cash or card. If not set, the terminal presents both options.
paymentobject
Settings for payment features.
contactlessCurrencystring
Min length: 3Max length: 3
The default currency for contactless payments on the payment terminal, as the three-letter ISO 4217 currency code.
hideMinorUnitsInCurrenciesarray[string]
Hides the minor units for the listed ISO currency codes.
receiptOptionsobject
Generic receipt settings.
logostring
Max length: 350000
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.
promptBeforePrintingboolean
Indicates whether a screen appears asking if you want to print the shopper receipt.
qrCodeDatastring
Data to print on the receipt as a QR code. This can include static text and the following variables:

${merchantreference}: the merchant reference of the transaction.

${pspreference}: the PSP reference of the transaction.

For example, http://www.example.com/order/${pspreference}/${merchantreference}.
receiptPrintingobject
Transaction outcomes that you want the terminal to print a merchant receipt or a shopper receipt for.
merchantApprovedboolean
Print a merchant receipt when the payment is approved.
merchantCancelledboolean
Print a merchant receipt when the transaction is cancelled.
merchantCaptureApprovedboolean
Print a merchant receipt when capturing the payment is approved.
merchantCaptureRefusedboolean
Print a merchant receipt when capturing the payment is refused.
merchantRefundApprovedboolean
Print a merchant receipt when the refund is approved.
merchantRefundRefusedboolean
Print a merchant receipt when the refund is refused.
merchantRefusedboolean
Print a merchant receipt when the payment is refused.
merchantVoidboolean
Print a merchant receipt when a previous transaction is voided.
shopperApprovedboolean
Print a shopper receipt when the payment is approved.
shopperCancelledboolean
Print a shopper receipt when the transaction is cancelled.
shopperCaptureApprovedboolean
Print a shopper receipt when capturing the payment is approved.
shopperCaptureRefusedboolean
Print a shopper receipt when capturing the payment is refused.
shopperRefundApprovedboolean
Print a shopper receipt when the refund is approved.
shopperRefundRefusedboolean
Print a shopper receipt when the refund is refused.
shopperRefusedboolean
Print a shopper receipt when the payment is refused.
shopperVoidboolean
Print a shopper receipt when a previous transaction is voided.
refundsobject
Settings for refunds.
referencedobject
Settings for referenced refunds.
enableStandaloneRefundsboolean
Indicates whether referenced refunds are enabled on the standalone terminal.
unreferencedobject
Settings for unreferenced refunds.
enableUnreferencedRefundsboolean
Indicates whether unreferenced refunds are enabled on the terminal.
signatureobject
Settings to skip signature, sign on display, or sign on receipt.
askSignatureOnScreenboolean
If skipSignature is false, indicates whether the shopper should provide a signature on the display (true) or on the merchant receipt (false).
deviceNamestring
Name that identifies the terminal.
deviceSloganstring
Max length: 50
Slogan shown on the start screen of the device.
skipSignatureboolean
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.
standaloneobject
Settings for standalone features.
currencyCodestring
Min length: 3Max length: 3
The default currency of the standalone payment terminal as an ISO 4217 currency code.
enableGratuitiesboolean
Indicates whether the tipping options specified in gratuities are enabled on the standalone terminal.
enableStandaloneboolean
Enable standalone mode.
storeAndForwardobject
Settings for store-and-forward offline payments. The maxAmount, maxPayments, and supportedCardTypes parameters must be configured, either in the request or inherited from a higher level in your account structure.
maxAmountarray[object]
The maximum amount that the terminal accepts for a single store-and-forward payment.
amountinteger
The transaction amount, in minor units.
currencyCodestring
The three-character ISO currency code.
maxPaymentsinteger
The maximum number of store-and-forward transactions per terminal that you can process while offline.
supportedCardTypesobject
The type of card for which the terminal accepts store-and-forward payments. You can specify multiple card types.
creditboolean
Set to true to accept credit cards.
debitboolean
Set to true to accept debit cards.
deferredDebitboolean
Set to true to accept cards that allow deferred debit.
prepaidboolean
Set to true to accept prepaid cards.
unknownboolean
Set to true to accept card types for which the terminal can't determine the funding source while offline.
surchargeobject
Settings for payment surcharge features.
askConfirmationboolean
Show the surcharge details on the terminal, so the shopper can confirm.
configurationsarray[object]
Surcharge fees or percentages for specific cards, funding sources (credit or debit), and currencies.
brandstring
Payment method, like eftpos_australia or mc. See the possible values.
commercialboolean
Set to true to apply surcharges only to commercial/business cards.
countryarray[string]
The country/region of the card issuer. If used, the surcharge settings only apply to the card issued in that country/region.
currenciesarray[object]
Currency and percentage or amount of the surcharge.
amountinteger
Surcharge amount per transaction, in minor units.
currencyCodestring
Three-character ISO currency code. For example, AUD.
maxAmountinteger
The maximum surcharge amount per transaction, in minor units.
percentagenumber
Surcharge percentage per transaction. The maximum number of decimal places is two. For example, 1% or 2.27%.
sourcesarray[string]
Funding source. Possible values:

Credit

Debit

excludeGratuityFromSurchargeboolean
Exclude the tip amount from the surcharge calculation.
tapToPayobject
Settings for Tap to Pay.
merchantDisplayNamestring
The text shown on the screen during the Tap to Pay transaction.
terminalInstructionsobject
Settings to define the behaviour of the payment terminal.
adyenAppRestartboolean
Indicates whether the Adyen app on the payment terminal restarts automatically when the configuration is updated.
timeoutsobject
Settings for device time-outs.
fromActiveToSleepinteger
Indicates the number of seconds of inactivity after which the terminal display goes into sleep mode.
wifiProfilesobject
Remote Wi-Fi profiles for WPA and WPA2 PSK and EAP Wi-Fi networks.
profilesarray[object]
List of remote Wi-Fi profiles.
authTypestring
The type of Wi-Fi network. Possible values: wpa-psk, wpa2-psk, wpa-eap, wpa2-eap.
autoWifiboolean
Indicates whether to automatically select the best authentication method available. Does not work on older terminal models.
bssTypestring
Use infra for infrastructure-based networks. This applies to most networks. Use adhoc only if the communication is p2p-based between base stations.
channelinteger
The channel number of the Wi-Fi network. The recommended setting is 0 for automatic channel selection.
defaultProfileboolean
Indicates whether this is your preferred wireless network. If true, the terminal will try connecting to this network first.
domainSuffixstring
Specifies the server domain name for EAP-TLS and EAP-PEAP WiFi profiles on Android 11 and above.
eapstring
For authType wpa-eap or wpa2-eap. Possible values: tls, peap, leap, fast
eapCaCertobject
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.
datastring
The certificate content converted to a Base64-encoded string.
namestring
The name of the certificate. Must be unique across Wi-Fi profiles.
eapClientCertobject
For eap tls. The certificate chain for the terminals. All terminals in the same network will use the same EAP client certificate.
datastring
The certificate content converted to a Base64-encoded string.
namestring
The name of the certificate. Must be unique across Wi-Fi profiles.
eapClientKeyobject
For eap tls. The RSA private key for the client. Include the lines BEGIN RSA PRIVATE KEY and END RSA PRIVATE KEY.
datastring
The certificate content converted to a Base64-encoded string.
namestring
The name of the certificate. Must be unique across Wi-Fi profiles.
eapClientPwdstring
For eap tls. The password of the RSA key file, if that file is password-protected.
eapIdentitystring
For authType wpa-eap or wpa2-eap. The EAP-PEAP username from your MS-CHAP account. Must match the configuration of your RADIUS server.
eapIntermediateCertobject
For eap tls. The EAP intermediate certificate.
datastring
The certificate content converted to a Base64-encoded string.
namestring
The name of the certificate. Must be unique across Wi-Fi profiles.
eapPwdstring
For eap peap. The EAP-PEAP password from your MS-CHAP account. Must match the configuration of your RADIUS server.
hiddenSsidboolean
Indicates if the 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.
namestring
Your name for the Wi-Fi profile.
pskstring
For authType **wpa-psk or wpa2-psk. The password to the wireless network.
ssidstring
The name of the wireless network.
wsecstring
The type of encryption. Possible values: auto, ccmp (recommended), tkip
settingsobject
General Wi-Fi settings.
bandstring
The preferred Wi-Fi band, for use if the terminals support multiple bands. Possible values: All, 2.4GHz, 5GHz.
roamingboolean
Indicates whether roaming is enabled on the terminals.
timeoutinteger
The connection time-out in seconds. Minimum value: 0.
204 - No Content
The request has been successfully processed, but there is no additional content.
400 - Bad Request
A problem reading or understanding the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
401 - Unauthorized
Authentication required.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
403 - Forbidden
Insufficient permissions to process the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
422 - Unprocessable Entity
A request validation error.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.
500 - Internal Server Error
The server could not process the request.
detailstring
A human-readable explanation specific to this occurrence of the problem.
errorCodestring
A code that identifies the problem type.
instancestring
A unique URI that identifies the specific occurrence of the problem.
invalidFieldsarray[object]
Detailed explanation of each validation error, when applicable.
messagestring
Description of the validation error.
namestring
The field that has an invalid value.
valuestring
The invalid value.
requestIdstring
A unique reference for the request, essentially the same as pspReference.
responseobject
JSON response payload.
statusinteger
The HTTP status code.
titlestring
A short, human-readable summary of the problem type.
typestring
A URI that identifies the problem type, pointing to human-readable documentation on this problem type.

Get terminal settings

HTTP Responses

200 - OK

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

422 - Unprocessable Entity

500 - Internal Server Error