Update terminal settings

patch/merchants/{merchantId}/terminalSettings

Updates payment terminal settings 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 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 restore a parameter value inherited from a 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.

To make this request, your API credential must have the following role:

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/v1/merchants/{merchantId}/terminalSettings

Path Parameters

Required

Optional

The unique identifier of the merchant account.

Request Parameters

Required

Optional

Settings to define the header of the shopper receipt.

Show children

Settings for terminal connectivity features.

Show children

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.

Show children

Settings for terminal hardware features.

Show children

Settings for localization.

Show children

Settings for a Terminal API integration.

Show children

The list of local and public URLs to send display notifications to when using Terminal API.

Show children

The key you share with Adyen to secure local communications when using Terminal API.

Show children

The list of local and public URLs to send event notifications to when using Terminal API.

Show children

One or more URLs to send event messages to when using Terminal API.

Configures sending event notifications by pressing a button on a terminal, for example used for pay-at-table.

Show children

Settings for offline payment features.

Show children

Settings for an Oracle Payment Interface (OPI) integration.

Show children

Settings for passcodes features.

Show children

Settings for Pay-at-table features.

Show children

Settings for payment features.

Show children

Generic receipt settings.

Show children

Transaction outcomes that you want the terminal to print a merchant receipt or a shopper receipt for.

Show children

Settings for refunds.

Show children

Settings to skip signature, sign on display, or sign on receipt.

Show children

Settings for standalone features.

Show children

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.

Show children

Settings for payment surcharge features.

Show children

Settings for Tap to Pay.

Show children

Settings to define the behaviour of the payment terminal.

Show children

Settings for device time-outs.

Show children

Remote Wi-Fi profiles for WPA and WPA2 PSK and EAP Wi-Fi networks.

Show children

List of remote Wi-Fi profiles.

Show children

The type of Wi-Fi network. Possible values: wpa-psk, wpa2-psk, wpa-eap, wpa2-eap.

Indicates whether to automatically select the best authentication method available. Does not work on older terminal models.

Use infra for infrastructure-based networks. This applies to most networks. Use adhoc only if the communication is p2p-based between base stations.

The channel number of the Wi-Fi network. The recommended setting is 0 for automatic channel selection.

Indicates whether this is your preferred wireless network. If true, the terminal will try connecting to this network first.

For authType wpa-eap or wpa2-eap. Possible values: tls, peap, leap, fast

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.

Show children

For eap tls. The certificate chain for the terminals. All terminals in the same network will use the same EAP client certificate.

Show children

For eap tls. The RSA private key for the client. Include the lines BEGIN RSA PRIVATE KEY and END RSA PRIVATE KEY.

Show children

For eap tls. The password of the RSA key file, if that file is password-protected.

For authType wpa-eap or wpa2-eap. The EAP-PEAP username from your MS-CHAP account. Must match the configuration of your RADIUS server.

For eap tls. The EAP intermediate certificate.

Show children

For eap peap. The EAP-PEAP password from your MS-CHAP account. Must match the configuration of your RADIUS server.

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.

Your name for the Wi-Fi profile.

For authType **wpa-psk or wpa2-psk. The password to the wireless network.

The name of the wireless network.

The type of encryption. Possible values: auto, ccmp (recommended), tkip

General Wi-Fi settings.

Show children

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.
Show moreShow less
cardholderReceiptobject
Settings to define the header of the shopper receipt.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
eventLocalUrlsarray[object]
One or more local URLs to send event notifications to when using Terminal API.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
displayUrlsobject
The list of local and public URLs to send display notifications to when using Terminal API.
Show children Hide children
localUrlsarray[object]
One or more local URLs to send notifications to when using Terminal API.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
identifierstring
The unique identifier of the shared key.
passphrasestring
The secure passphrase to protect the shared key.
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.
Show children Hide children
eventLocalUrlsarray[object]
One or more local URLs to send event notifications to when using Terminal API.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
amountinteger
The transaction amount, in minor units.
currencyCodestring
The three-character ISO currency code.
opiobject
Settings for an Oracle Payment Interface (OPI) integration.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
referencedobject
Settings for referenced refunds.
Show children Hide children
enableStandaloneRefundsboolean
Indicates whether referenced refunds are enabled on the standalone terminal.
signatureobject
Settings to skip signature, sign on display, or sign on receipt.
Show children Hide children
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.
Show children Hide children
currencyCodestring
Min length: 3Max length: 3
The default currency of the standalone payment terminal as an ISO 4217 currency code.
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.
Show children Hide children
maxAmountarray[object]
The maximum amount that the terminal accepts for a single store-and-forward payment.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
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

tapToPayobject
Settings for Tap to Pay.
Show children Hide children
merchantDisplayNamestring
The text shown on the screen during the Tap to Pay transaction.
terminalInstructionsobject
Settings to define the behaviour of the payment terminal.
Show children Hide children
adyenAppRestartboolean
Indicates whether the Adyen app on the payment terminal restarts automatically when the configuration is updated.
timeoutsobject
Settings for device time-outs.
Show children Hide children
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.
Show children Hide children
profilesarray[object]
List of remote Wi-Fi profiles.
Show children Hide children
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.
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.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
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.
Show children Hide children
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.
Show more Show less
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[InvalidFieldWrapper]
Detailed explanation of each validation error, when applicable.
Show children Hide children
InvalidFieldobject
Show children Hide children
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.
Show more Show less
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[InvalidFieldWrapper]
Detailed explanation of each validation error, when applicable.
Show children Hide children
InvalidFieldobject
Show children Hide children
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.
Show more Show less
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[InvalidFieldWrapper]
Detailed explanation of each validation error, when applicable.
Show children Hide children
InvalidFieldobject
Show children Hide children
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.
Show more Show less
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[InvalidFieldWrapper]
Detailed explanation of each validation error, when applicable.
Show children Hide children
InvalidFieldobject
Show children Hide children
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.
Show more Show less
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[InvalidFieldWrapper]
Detailed explanation of each validation error, when applicable.
Show children Hide children
InvalidFieldobject
Show children Hide children
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.

Update terminal settings

Path Parameters

Request Parameters

Response parameters

HTTP Responses

200 - OK

204 - No Content

400 - Bad Request

401 - Unauthorized

403 - Forbidden

422 - Unprocessable Entity

500 - Internal Server Error