{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/adyen/main/json-schema/adyen-terminal-settings-schema.json", "title": "TerminalSettings", "x-generated": "2026-10-12", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/adyen-companies-api-openapi.yml#/components/schemas/TerminalSettings", "properties": { "cardholderReceipt": { "description": "Settings to define the header of the shopper receipt.", "$ref": "#/$defs/CardholderReceipt" }, "connectivity": { "description": "Settings for terminal connectivity features.", "$ref": "#/$defs/Connectivity" }, "gratuities": { "description": "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.", "items": { "$ref": "#/$defs/Gratuity" }, "type": "array" }, "hardware": { "description": "Settings for terminal hardware features.", "$ref": "#/$defs/Hardware" }, "localization": { "description": "Settings for localization.", "$ref": "#/$defs/Localization" }, "nexo": { "description": "Settings for a Terminal API integration.", "$ref": "#/$defs/Nexo" }, "offlineProcessing": { "description": "Settings for [offline payment](https://docs.adyen.com/point-of-sale/offline-payments) features.", "$ref": "#/$defs/OfflineProcessing" }, "opi": { "description": "Settings for an Oracle Payment Interface (OPI) integration.", "$ref": "#/$defs/Opi" }, "passcodes": { "description": "Settings for [passcodes](https://docs.adyen.com/point-of-sale/managing-terminals/menu-access?tab=manage_passcodes_with_an_api_call_2#manage-passcodes) features.", "$ref": "#/$defs/Passcodes" }, "payAtTable": { "description": "Settings for [Pay-at-table](https://docs.adyen.com/point-of-sale/pay-at-x) features.", "$ref": "#/$defs/PayAtTable" }, "payment": { "description": "Settings for payment features.", "$ref": "#/$defs/Payment" }, "receiptOptions": { "description": "Generic receipt settings.", "$ref": "#/$defs/ReceiptOptions" }, "receiptPrinting": { "description": "Transaction outcomes that you want the terminal to print a merchant receipt or a shopper receipt for.", "$ref": "#/$defs/ReceiptPrinting" }, "refunds": { "description": "Settings for refunds.", "$ref": "#/$defs/Refunds" }, "signature": { "description": "Settings to skip signature, sign on display, or sign on receipt.", "$ref": "#/$defs/Signature" }, "standalone": { "description": "Settings for [standalone](https://docs.adyen.com/point-of-sale/standalone/standalone-build/set-up-standalone#set-up-standalone-using-an-api-call) features.", "$ref": "#/$defs/Standalone" }, "surcharge": { "description": "Settings for payment [surcharge](https://docs.adyen.com/point-of-sale/surcharge) features.", "$ref": "#/$defs/Surcharge" }, "tapToPay": { "description": "Settings for Tap to Pay.", "$ref": "#/$defs/TapToPay" }, "timeouts": { "description": "Settings for device [time-outs](https://docs.adyen.com/point-of-sale/pos-timeouts#device-time-out).", "$ref": "#/$defs/Timeouts" }, "wifiProfiles": { "description": "Remote Wi-Fi profiles for WPA and WPA2 PSK and EAP Wi-Fi networks.", "$ref": "#/$defs/WifiProfiles" } }, "type": "object", "$defs": { "CardholderReceipt": { "properties": { "headerForAuthorizedReceipt": { "description": "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`", "type": "string" } }, "type": "object" }, "Configuration": { "properties": { "brand": { "description": "Payment method, like **eftpos_australia** or **mc**. See the [possible values](https://docs.adyen.com/development-resources/paymentmethodvariant#management-api). ", "type": "string" }, "country": { "description": "Countries, to filter different surcharge amounts for domestic or international cards.", "items": { "type": "string" }, "type": "array" }, "currencies": { "description": "Currency, and surcharge percentage or amount.", "items": { "$ref": "#/$defs/Currency" }, "type": "array" }, "sources": { "description": "Funding source. Possible values:\n* **Credit**\n* **Debit**", "items": { "type": "string" }, "type": "array" } }, "required": [ "brand", "currencies" ], "type": "object" }, "Connectivity": { "properties": { "simcardStatus": { "description": "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.\n\nPossible values:\n* **ACTIVATED**: the SIM card is activated. Cellular connectivity may still need to be enabled on the terminal itself, in the **Network** settings.\n* **INVENTORY**: the SIM card is not activated. The terminal can't use cellular connectivity.", "enum": [ "ACTIVATED", "INVENTORY" ], "type": "string" } }, "type": "object" }, "Currency": { "properties": { "amount": { "description": "Surcharge amount per transaction, in [minor units](https://docs.adyen.com/development-resources/currency-codes).", "format": "int32", "type": "integer" }, "currencyCode": { "description": "Three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes). For example, **AUD**.", "type": "string" }, "percentage": { "description": "Surcharge percentage per transaction. The maximum number of decimal places is two. For example, **1%** or **2.27%**.", "format": "double", "type": "number" } }, "required": [ "currencyCode" ], "type": "object" }, "EventUrl": { "properties": { "eventLocalUrls": { "description": "One or more local URLs to send event notifications to when using Terminal API.", "items": { "$ref": "#/$defs/Url" }, "type": "array" }, "eventPublicUrls": { "description": "One or more public URLs to send event notifications to when using Terminal API.", "items": { "$ref": "#/$defs/Url" }, "type": "array" } }, "type": "object" }, "File": { "properties": { "data": { "description": "The certificate content converted to a Base64-encoded string.", "type": "string" }, "name": { "description": "The name of the certificate. Must be unique across Wi-Fi profiles.", "type": "string" } }, "required": [ "name", "data" ], "type": "object" }, "Gratuity": { "properties": { "allowCustomAmount": { "description": "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.", "type": "boolean" }, "currency": { "description": "The currency that the tipping settings apply to.", "type": "string" }, "predefinedTipEntries": { "description": "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.\nThe options can be a mix of:\n\n- A percentage of the transaction amount. Example: **5%**\n- A tip amount in [minor units](https://docs.adyen.com/development-resources/currency-codes). Example: **500** for a EUR 5 tip.", "items": { "type": "string" }, "type": "array" }, "usePredefinedTipEntries": { "description": "Indicates whether the terminal shows a prompt to enter a tip (**false**), or predefined tipping options to choose from (**true**).", "type": "boolean" } }, "type": "object" }, "Hardware": { "properties": { "displayMaximumBackLight": { "description": "The brightness of the display when the terminal is being used, expressed as a percentage.", "format": "int32", "type": "integer" }, "resetTotalsHour": { "description": "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.", "format": "int32", "type": "integer" }, "restartHour": { "description": "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.", "format": "int32", "type": "integer" } }, "type": "object" }, "Key": { "properties": { "identifier": { "description": "The unique identifier of the shared key.", "type": "string" }, "passphrase": { "description": "The secure passphrase to protect the shared key.", "type": "string" }, "version": { "description": "The version number of the shared key.", "format": "int32", "type": "integer" } }, "type": "object" }, "Localization": { "properties": { "language": { "description": "Language of the terminal.", "type": "string" }, "secondaryLanguage": { "description": "Secondary language of the terminal.", "type": "string" }, "timezone": { "description": "The time zone of the terminal.", "type": "string" } }, "type": "object" }, "MinorUnitsMonetaryValue": { "properties": { "amount": { "description": "The transaction amount, in [minor units](https://docs.adyen.com/development-resources/currency-codes).", "format": "int32", "type": "integer" }, "currencyCode": { "description": "The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes).", "type": "string" } }, "type": "object" }, "Nexo": { "properties": { "displayUrls": { "description": "The list of local and public URLs to send display notifications to when using Terminal API.", "$ref": "#/$defs/NotificationUrl" }, "encryptionKey": { "description": "The key you share with Adyen to secure local communications when using Terminal API.", "$ref": "#/$defs/Key" }, "eventUrls": { "description": "The list of local and public URLs to send event notifications to when using Terminal API.", "$ref": "#/$defs/EventUrl" }, "nexoEventUrls": { "deprecated": true, "x-deprecatedInVersion": "1", "x-deprecatedMessage": "Use `eventUrls` instead.", "description": "One or more URLs to send event messages to when using Terminal API.", "items": { "type": "string" }, "type": "array" }, "notification": { "description": "Configures sending event notifications by pressing a button on a terminal, for example used for pay-at-table.", "$ref": "#/$defs/Notification" } }, "type": "object" }, "Notification": { "properties": { "category": { "description": "The type of event notification sent when you select the notification button.", "enum": [ "SaleWakeUp", "KeyPressed" ], "type": "string" }, "details": { "description": "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.", "type": "string" }, "enabled": { "description": "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.", "type": "boolean" }, "showButton": { "description": "Shows or hides the event notification button on the screen of terminal models that have a keypad.", "type": "boolean" }, "title": { "description": "The name of the notification button on the terminal screen.", "type": "string" } }, "type": "object" }, "NotificationUrl": { "properties": { "localUrls": { "description": "One or more local URLs to send notifications to when using Terminal API.", "items": { "$ref": "#/$defs/Url" }, "type": "array" }, "publicUrls": { "description": "One or more public URLs to send notifications to when using Terminal API.", "items": { "$ref": "#/$defs/Url" }, "type": "array" } }, "type": "object" }, "OfflineProcessing": { "properties": { "chipFloorLimit": { "description": "The maximum offline transaction amount for chip cards, in the processing currency and specified in [minor units](https://docs.adyen.com/development-resources/currency-codes).", "format": "int32", "type": "integer" }, "offlineSwipeLimits": { "description": "The maximum offline transaction amount for swiped cards, in the specified currency.", "items": { "$ref": "#/$defs/MinorUnitsMonetaryValue" }, "type": "array" } }, "type": "object" }, "Opi": { "properties": { "enablePayAtTable": { "description": "Indicates if Pay at table is enabled.", "type": "boolean" }, "payAtTableStoreNumber": { "description": "The store number to use for Pay at Table.", "type": "string" }, "payAtTableURL": { "description": "The URL and port number used for Pay at Table communication.", "type": "string" } }, "type": "object" }, "Passcodes": { "properties": { "adminMenuPin": { "description": "The passcode for the Admin menu and the Settings menu.", "maxLength": 6, "type": "string" }, "refundPin": { "description": "The passcode for referenced and unreferenced refunds on standalone terminals.", "maxLength": 6, "type": "string" }, "screenLockPin": { "description": "The passcode to unlock the terminal screen after a timeout.", "maxLength": 6, "minLength": 4, "type": "string" }, "txMenuPin": { "description": "The passcode for the Transactions menu.", "maxLength": 6, "type": "string" } }, "type": "object" }, "PayAtTable": { "properties": { "authenticationMethod": { "description": "Allowed authentication methods: Magswipe, Manual Entry.", "enum": [ "MAGSWIPE", "MKE" ], "type": "string" }, "enablePayAtTable": { "description": "Enable Pay at table.", "type": "boolean" }, "paymentInstrument": { "description": "Sets the allowed payment instrument for Pay at table transactions. Can be: **cash** or **card**. If not set, the terminal presents both options.", "enum": [ "Cash", "Card" ], "type": "string" } }, "type": "object" }, "Payment": { "properties": { "contactlessCurrency": { "description": "The default currency for contactless payments on the payment terminal, as the three-letter [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code.", "maxLength": 3, "minLength": 3, "type": "string" }, "hideMinorUnitsInCurrencies": { "description": "Hides the minor units for the listed [ISO currency codes](https://en.wikipedia.org/wiki/ISO_4217).", "items": { "type": "string" }, "type": "array" } }, "type": "object" }, "Profile": { "properties": { "authType": { "description": "The type of Wi-Fi network. Possible values: **wpa-psk**, **wpa2-psk**, **wpa-eap**, **wpa2-eap**.", "type": "string" }, "autoWifi": { "description": "Indicates whether to automatically select the best authentication method available. Does not work on older terminal models.", "type": "boolean" }, "bssType": { "description": "Use **infra** for infrastructure-based networks. This applies to most networks. Use **adhoc** only if the communication is p2p-based between base stations.", "type": "string" }, "channel": { "description": "The channel number of the Wi-Fi network. The recommended setting is **0** for automatic channel selection.", "format": "int32", "type": "integer" }, "defaultProfile": { "description": "Indicates whether this is your preferred wireless network. If **true**, the terminal will try connecting to this network first.", "type": "boolean" }, "eap": { "description": "For `authType` **wpa-eap** or **wpa2-eap**. Possible values: **tls**, **peap**, **leap**, **fast**", "type": "string" }, "eapCaCert": { "description": "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.", "$ref": "#/$defs/File" }, "eapClientCert": { "description": "For `eap` **tls**. The certificate chain for the terminals. All terminals in the same network will use the same EAP client certificate.", "$ref": "#/$defs/File" }, "eapClientKey": { "description": "For `eap` **tls**. The RSA private key for the client. Include the lines BEGIN RSA PRIVATE KEY and END RSA PRIVATE KEY.", "$ref": "#/$defs/File" }, "eapClientPwd": { "description": "For `eap` **tls**. The password of the RSA key file, if that file is password-protected.", "type": "string" }, "eapIdentity": { "description": "For `authType` **wpa-eap** or **wpa2-eap**. The EAP-PEAP username from your MS-CHAP account. Must match the configuration of your RADIUS server.", "type": "string" }, "eapIntermediateCert": { "description": "For `eap` **tls**. The EAP intermediate certificate.", "$ref": "#/$defs/File" }, "eapPwd": { "description": "For `eap` **peap**. The EAP-PEAP password from your MS-CHAP account. Must match the configuration of your RADIUS server.", "type": "string" }, "hiddenSsid": { "description": "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.", "type": "boolean" }, "name": { "description": "Your name for the Wi-Fi profile.", "type": "string" }, "psk": { "description": "For `authType` **wpa-psk or **wpa2-psk**. The password to the wireless network.", "type": "string" }, "ssid": { "description": "The name of the wireless network.", "type": "string" }, "wsec": { "description": "The type of encryption. Possible values: **auto**, **ccmp** (recommended), **tkip**", "type": "string" } }, "required": [ "ssid", "bssType", "authType", "wsec" ], "type": "object" }, "ReceiptOptions": { "properties": { "logo": { "description": "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.", "maxLength": 350000, "type": "string" }, "promptBeforePrinting": { "description": "Indicates whether a screen appears asking if you want to print the shopper receipt.", "type": "boolean" }, "qrCodeData": { "description": "Data to print on the receipt as a QR code. This can include static text and the following variables:\n\n- `${merchantreference}`: the merchant reference of the transaction.\n- `${pspreference}`: the PSP reference of the transaction.\n\n For example, **http://www.example.com/order/${pspreference}/${merchantreference}**.", "type": "string" } }, "type": "object" }, "ReceiptPrinting": { "properties": { "merchantApproved": { "description": "Print a merchant receipt when the payment is approved.", "type": "boolean" }, "merchantCancelled": { "description": "Print a merchant receipt when the transaction is cancelled.", "type": "boolean" }, "merchantCaptureApproved": { "description": "Print a merchant receipt when capturing the payment is approved.", "type": "boolean" }, "merchantCaptureRefused": { "description": "Print a merchant receipt when capturing the payment is refused.", "type": "boolean" }, "merchantRefundApproved": { "description": "Print a merchant receipt when the refund is approved.", "type": "boolean" }, "merchantRefundRefused": { "description": "Print a merchant receipt when the refund is refused.", "type": "boolean" }, "merchantRefused": { "description": "Print a merchant receipt when the payment is refused.", "type": "boolean" }, "merchantVoid": { "description": "Print a merchant receipt when a previous transaction is voided.", "type": "boolean" }, "shopperApproved": { "description": "Print a shopper receipt when the payment is approved.", "type": "boolean" }, "shopperCancelled": { "description": "Print a shopper receipt when the transaction is cancelled.", "type": "boolean" }, "shopperCaptureApproved": { "description": "Print a shopper receipt when capturing the payment is approved.", "type": "boolean" }, "shopperCaptureRefused": { "description": "Print a shopper receipt when capturing the payment is refused.", "type": "boolean" }, "shopperRefundApproved": { "description": "Print a shopper receipt when the refund is approved.", "type": "boolean" }, "shopperRefundRefused": { "description": "Print a shopper receipt when the refund is refused.", "type": "boolean" }, "shopperRefused": { "description": "Print a shopper receipt when the payment is refused.", "type": "boolean" }, "shopperVoid": { "description": "Print a shopper receipt when a previous transaction is voided.", "type": "boolean" } }, "type": "object" }, "Referenced": { "properties": { "enableStandaloneRefunds": { "description": "Indicates whether referenced refunds are enabled on the standalone terminal.", "type": "boolean" } }, "type": "object" }, "Refunds": { "properties": { "referenced": { "description": "Settings for referenced refunds.", "$ref": "#/$defs/Referenced" } }, "type": "object" }, "Settings": { "properties": { "band": { "description": "The preferred Wi-Fi band, for use if the terminals support multiple bands. Possible values: All, 2.4GHz, 5GHz.", "type": "string" }, "roaming": { "description": "Indicates whether roaming is enabled on the terminals.", "type": "boolean" }, "timeout": { "description": "The connection time-out in seconds. Minimum value: 0.", "format": "int32", "type": "integer" } }, "type": "object" }, "Signature": { "properties": { "askSignatureOnScreen": { "description": "If `skipSignature` is false, indicates whether the shopper should provide a signature on the display (**true**) or on the merchant receipt (**false**).", "type": "boolean" }, "deviceName": { "description": "Name that identifies the terminal.", "type": "string" }, "deviceSlogan": { "description": "Slogan shown on the start screen of the device.", "maxLength": 50, "type": "string" }, "skipSignature": { "description": "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.", "type": "boolean" } }, "type": "object" }, "Standalone": { "properties": { "currencyCode": { "description": "The default currency of the standalone payment terminal as an [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) currency code.", "maxLength": 3, "minLength": 3, "type": "string" }, "enableStandalone": { "description": "Enable standalone mode.", "type": "boolean" } }, "type": "object" }, "Surcharge": { "properties": { "askConfirmation": { "description": "Show the surcharge details on the terminal, so the shopper can confirm.", "type": "boolean" }, "configurations": { "description": "Surcharge fees or percentages for specific payment methods, funding sources (credit or debit), and currencies.", "items": { "$ref": "#/$defs/Configuration" }, "type": "array" } }, "type": "object" }, "TapToPay": { "properties": { "merchantDisplayName": { "description": "The text shown on the screen during the Tap to Pay transaction.", "type": "string" } }, "type": "object" }, "Timeouts": { "properties": { "fromActiveToSleep": { "description": "Indicates the number of seconds of inactivity after which the terminal display goes into sleep mode.", "format": "int32", "type": "integer" } }, "type": "object" }, "Url": { "properties": { "encrypted": { "description": "Indicates if the message sent to this URL should be encrypted.", "type": "boolean" }, "password": { "description": "The password for authentication of the notifications.", "type": "string" }, "url": { "description": "The URL in the format: http(s)://domain.com.", "type": "string" }, "username": { "description": "The username for authentication of the notifications.", "type": "string" } }, "type": "object" }, "WifiProfiles": { "properties": { "profiles": { "description": "List of remote Wi-Fi profiles.", "items": { "$ref": "#/$defs/Profile" }, "type": "array" }, "settings": { "description": "General Wi-Fi settings.", "$ref": "#/$defs/Settings" } }, "type": "object" } } }