--- title: "Event notifications" description: "Receive terminal-generated event notifications in your POS app." url: "https://docs.adyen.com/point-of-sale/design-your-integration/notifications/event-notifications" source_url: "https://docs.adyen.com/point-of-sale/design-your-integration/notifications/event-notifications.md" canonical: "https://docs.adyen.com/point-of-sale/design-your-integration/notifications/event-notifications" last_modified: "2025-07-14T16:00:00+02:00" language: "en" --- # Event notifications Receive terminal-generated event notifications in your POS app. [View source](/point-of-sale/design-your-integration/notifications/event-notifications.md) From time to time, your payment terminal encounters an issue, or needs to perform maintenance. When this happens, the terminal generates an event notification. You can use event notifications in your POS app to inform your staff of the terminal's availability and state. If your integration uses [asynchronous cloud communications](/point-of-sale/design-your-integration/choose-your-architecture/cloud#async), you must set up event notifications. We then send the Terminal API responses to your endpoint. Here we describe how to set up event notifications. You can do this in your [Customer Area](#set-up-in-ca) or by using [API calls](#set-up-event-notifications-using-api-calls). You then receive webhooks that include a Terminal API [`EventNotification` ](#event-notification-types)and, if applicable, a Terminal API [asynchronous `SaleToPOIResponse`](#async-response). You can use the received information to show a message in your POS app. ## Set up event notifications in the Customer Area To get event notifications and, if applicable, asynchronous Terminal API responses, you need to make sure you can receive HTTP callbacks (webhooks) on a specific endpoint. Then you need to provide the URL to that endpoint in your Customer Area. Make sure to [acknowledge](#accept-event-notifications) that your POS system successfully received an event notification from the terminal. 1. Prepare your system. It needs to have: * An endpoint that can receive JSON messages. * For the test environment: an open TCP port for HTTP traffic (80, 8080, or 8888) or HTTPS traffic (443, 8443, or 8843) with TLSv1.2. * For the live environment: an open TCP port for HTTPS traffic (443, 8443, or 8843) with TLSv1.2. 2. Log in to your [test Customer Area](https://ca-test.adyen.com/). 3. Switch to the merchant account, store, or terminal that you want to set up notifications for. 4. Go to **In-person payments** > **Terminal settings** > **Integrations**. 5. In the **Terminal API** section, select **Decrypted**. 6. Under **Event URLs**, select **Add new**. 7. Select the pencil icon **next to the field that appears.\ The **Add URL** dialog opens. 8. Enter the details: * **URL**: the URL of the endpoint where you want to receive event notifications. * **Username** and **Password** (optional): the basic authentication credentials you set up on your server. We include these details in the header of the notification to authenticate with your server. * **Public**: select this option if the specified URL is on a public network. * **Local**: select this option if the specified URL is on a Local Area Network. * **Enable encryption**: select this if you want the message sent to this URL to be encrypted. 9. Select **Add URL**. 10. Select **Save**. Event notifications will now be sent to the endpoint you specified. If you are using cloud communications with an asynchronous result, the Terminal API responses are also sent to this endpoint. ## Set up event notifications using API calls Instead of [using your Customer Area](#set-up-in-ca), you can use our [Management API](/point-of-sale/automating-terminal-management/configure-terminals-api) to automate setting up display notifications. To get display notifications, make sure you can receive HTTP callbacks (webhooks) on a specific endpoint. You then need to provide the URL to that endpoint in the PATCH request. Make sure to [acknowledge](#accept-event-notifications) that your POS system successfully received an event notification from the terminal. To set up event notifications, you need to have the following [role](/development-resources/api-credentials#api-permissions): * Management API—Terminal Advanced settings read and write Proceed as follows: 1. Prepare your system. It needs to have: * An endpoint that can receive JSON messages. * For the test environment: an open TCP port for HTTP traffic (80, 8080, or 8888) or HTTPS traffic (443, 8443, or 8843) with TLSv1.2. * For the live environment: an open TCP port for HTTPS traffic (443, 8443, or 8843) with TLSv1.2. 2. Optional. To see what display notification settings have already been configured, make a GET request to the `/terminalSettings` endpoint for the [company account](https://docs.adyen.com/api-explorer/Management/latest/get/companies/\(companyId\)/terminalSettings), [merchant account](https://docs.adyen.com/api-explorer/Management/latest/get/merchants/\(merchantId\)/terminalSettings), [store](https://docs.adyen.com/api-explorer/Management/latest/get/stores/\(storeId\)/terminalSettings) or [terminal](https://docs.adyen.com/api-explorer/Management/latest/get/terminals/\(terminalId\)/terminalSettings), and check the `nexo.eventUrls` object. When removing settings, you need to know the settings that will be [inherited](/point-of-sale/automating-terminal-management/configure-terminals-api#inheritance) from the next higher level. 3. Make a PATCH request to the `/terminalSettings` endpoint on the [company account](https://docs.adyen.com/api-explorer/Management/latest/get/companies/\(companyId\)/terminalSettings), [merchant account](https://docs.adyen.com/api-explorer/Management/latest/get/merchants/\(merchantId\)/terminalSettings), [store](https://docs.adyen.com/api-explorer/Management/latest/get/stores/\(storeId\)/terminalSettings) or [terminal](https://docs.adyen.com/api-explorer/Management/latest/get/terminals/\(terminalId\)/terminalSettings) level.\ In the request body, inside the [nexo](https://docs.adyen.com/api-explorer/Management/latest/patch/companies/\(companyId\)/terminalSettings#request-nexo) object, specify: * `eventLocalUrls`: an array with one or more local URLs. Use this if the specified URL is on a Local Area Network. This includes: | Parameter | Data type | Description | | ----------- | --------- | ----------------------------------------------------------------------------------------------------- | | `encrypted` | Boolean | Indicates if the message sent to this URL should be encrypted. | | `password` | String | The password for authentication of the notifications. | | `url` | String | The URL of the endpoint where you want to receive notifications, in the format: http(s)://domain.com. | | `username` | String | The username for authentication of the notifications. | * `eventPublicUrls`: an array with one or more public URLs. Use this if the specified URL is on a public network. This includes: | Parameter | Data type | Description | | ----------- | --------- | ----------------------------------------------------------------------------------------------------- | | `encrypted` | Boolean | Indicates if the message sent to this URL should be encrypted. | | `password` | String | The password for authentication of the notifications. | | `url` | String | The URL of the endpoint where you want to receive notifications, in the format: http(s)://domain.com. | | `username` | String | The username for authentication of the notifications. | **Set up a local URL on a terminal level** ```json curl https://management-test.adyen.com/v3/terminals/{terminalId}/terminalSettings \ -H 'x-API-key: ADYEN_API_KEY' \ -X PATCH \ -d '{ "nexo": { "eventUrls":{ "eventLocalUrls":[ { "encrypted":"true", "password":"CREDENTIAL_PASSWORD", "url":"https://your-event-notifications-endpoint.com", "username":"CREDENTIAL_USERNAME" } ] } } }' ``` 4. When you receive the response, note that this returns the entire configuration at the level where you made the request. **Response with the entire configuration on a terminal level** ```json { "cardholderReceipt":{ "headerForAuthorizedReceipt":"header1,header2,filler" }, "gratuities":[ { "currency":"EUR", "usePredefinedTipEntries":true, "predefinedTipEntries":[ "100", "1%", "5%" ], "allowCustomAmount":true } ], "nexo":{ "displayUrls":{ "localUrls":[ { "password":"CREDENTIAL_PASSWORD", "url":"https://your-display-notifications-endpoint.com", "username":"CREDENTIAL_USERNAME" } ] }, "encryptionKey":{ "identifier":"KEY_IDENTIFIER", "passphrase":"KEY_PASSPHRASE", "version":1 }, "eventUrls":{ "eventPublicUrls":[ { "password":"CREDENTIAL_PASSWORD", "url":"https://your-event-notifications-endpoint.com", "username":"CREDENTIAL_USERNAME" } ] } }, "opi":{ "enablePayAtTable":true, "payAtTableStoreNumber":"1", "payAtTableURL":"https:/your-pay-at-table-endpoint.com" }, "offlineProcessing":{ "chipFloorLimit":0 }, "receiptOptions":{ "qrCodeData":"http://www.example.com/order/${pspreference}/${merchantreference}" }, "receiptPrinting":{ "shopperApproved":true, "shopperRefused":true, "shopperCancelled":true, "shopperRefundApproved":true, "shopperRefundRefused":true, "shopperVoid":true }, "signature":{ "askSignatureOnScreen":true, "skipSignature":false, "deviceName":"Amsterdam-236203386" }, "wifiProfiles":{ "profiles":[ { "authType":"wpa-psk", "autoWifi":false, "bssType":"infra", "channel":0, "defaultProfile":true, "hiddenSsid":false, "name":"Guest Wi-Fi", "psk":"4R8R2R3V456X", "ssid":"G470P37660D4G", "wsec":"ccmp" } ], "settings":{ "band":"All", "roaming":true } }, "timeouts":{ "fromActiveToSleep":30 }, "hardware":{ "displayMaximumBackLight":75 }, "connectivity":{ "simcardStatus":"INVENTORY" } } ``` ## Accept event notifications We require you to acknowledge that your POS system successfully received an event notification from the terminal with a [successful HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#successful_responses), for example **202**. This prevents the terminal or our backend from repeatedly re-sending the same notification. When your POS system receives an event notification: 1. Store the event notification in your database. 2. Acknowledge the event notification with a [successful HTTP response status code](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status#successful_responses), for example **202**. 3. Apply your business logic.\ Make sure that you acknowledge the event notification before you apply any business logic, because an error in your business logic can prevent event notifications with important updates from reaching your system. ## Event notification types Each notification contains a unique `DeviceID` and a `EventToNotify` value. You can use `EventToNotify` to show a message in your POS app informing your staff of the terminal's state. | Event | Description | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `Shutdown` | The terminal is shutting down. | | `BeginMaintenance` | Terminal maintenance is starting. | | `EndMaintenance` | Terminal maintenance is finishing. | | `OutOfOrder` | The terminal is out of order. | | `Initialised` | The terminal has been initialized. | | `NetworkConnected` | The terminal is connected to your POS system over the internet. | | `NetworkDisconnected` | The terminal is disconnected from your POS system. | | `Reject` | A request was rejected. The `EventDetails` element contains an explanation of the error. | | `SaleWakeUp` | The terminal is starting a payment request. The `EventDetails` element contains the reference number that was entered on the terminal. | | `UseAnotherCardForPreauth` | The terminal requests a different card brand that supports pre-authorisation and authorisation adjustment. | ## Event notification examples ### Shutdown **Shutdown** ```json { "SaleToPOIRequest":{ "EventNotification":{ "EventDetails":"newstate=IDLE&oldstate=START", "EventToNotify":"Shutdown", "TimeStamp":"2019-08-07T10:16:10.000Z" }, "MessageHeader":{ "SaleID":"POSSystemID12345", "ProtocolVersion":"3.0", "MessageType":"Notification", "POIID":"V400m-324688179", "MessageClass":"Event", "MessageCategory":"Event", "DeviceID":"1517998561" } } } ``` ### BeginMaintenance **Example notification** ```json { "SaleToPOIRequest":{ "EventNotification":{ "EventDetails":"newstate=IDLE&oldstate=START", "EventToNotify":"BeginMaintenance", "TimeStamp":"2019-08-07T10:16:10.000Z" }, "MessageHeader":{ "SaleID":"POSSystemID12345", "ProtocolVersion":"3.0", "MessageType":"Notification", "POIID":"V400m-324688179", "MessageClass":"Event", "MessageCategory":"Event", "DeviceID":"1517998562" } } } ``` ### EndMaintenance **Example notification** ```json { "SaleToPOIRequest":{ "EventNotification":{ "EventDetails":"newstate=IDLE&oldstate=START", "EventToNotify":"EndMaintenance", "TimeStamp":"2019-08-07T10:16:10.000Z" }, "MessageHeader":{ "SaleID":"POSSystemID12345", "ProtocolVersion":"3.0", "MessageType":"Notification", "POIID":"V400m-324688179", "MessageClass":"Event", "MessageCategory":"Event", "DeviceID":"1517998561" } } } ``` ### OutOfOrder **Example notification** ```json { "SaleToPOIRequest":{ "EventNotification":{ "EventDetails":"newstate=IDLE&oldstate=START", "EventToNotify":"OutOfOrder", "TimeStamp":"2019-08-07T10:16:10.000Z" }, "MessageHeader":{ "SaleID":"POSSystemID12345", "ProtocolVersion":"3.0", "MessageType":"Notification", "POIID":"V400m-324688179", "MessageClass":"Event", "MessageCategory":"Event", "DeviceID":"1517998563" } } } ``` ### Initialised **Example notification** ```json { "SaleToPOIRequest":{ "EventNotification":{ "EventDetails":"newstate=IDLE&oldstate=START", "EventToNotify":"Initialised", "TimeStamp":"2019-08-07T10:16:10.000Z" }, "MessageHeader":{ "SaleID":"POSSystemID12345", "ProtocolVersion":"3.0", "MessageType":"Notification", "POIID":"V400m-324688179", "MessageClass":"Event", "MessageCategory":"Event", "DeviceID":"1517998564" } } } ``` ### NetworkConnected **Example notification** ```json { "SaleToPOIRequest":{ "EventNotification":{ "EventDetails":"message=Terminal V400m-324688179 connected", "EventToNotify":"NetworkConnected", "TimeStamp":"2025-05-07T10:16:10.000Z" }, "MessageHeader":{ "SaleID":"POSSystemID12345", "ProtocolVersion":"3.0", "MessageType":"Notification", "POIID":"V400m-324688179", "MessageClass":"Event", "MessageCategory":"Event", "DeviceID":"1517998565" } } } ``` ### NetworkDisconnected **Example notification** ```json { "SaleToPOIRequest":{ "EventNotification":{ "EventDetails":"message=Terminal V400m-324688179 disconnected", "EventToNotify":"NetworkDisconnected", "TimeStamp":"2025-05-07T10:16:10.000Z" }, "MessageHeader":{ "SaleID":"POSSystemID12345", "ProtocolVersion":"3.0", "MessageType":"Notification", "POIID":"V400m-324688179", "MessageClass":"Event", "MessageCategory":"Event", "DeviceID":"1517998565" } } } ``` ### Reject **Example notification** ```json { "SaleToPOIRequest":{ "EventNotification":{ "EventDetails":"newstate=IDLE&oldstate=START", "EventToNotify":"Reject", "TimeStamp":"2019-08-07T10:16:10.000Z" }, "MessageHeader":{ "SaleID":"POSSystemID12345", "ProtocolVersion":"3.0", "MessageType":"Notification", "POIID":"V400m-324688179", "MessageClass":"Event", "MessageCategory":"Event", "DeviceID":"1517998565" } } } ``` ### SaleWakeUp **Example notification** ```json { "SaleToPOIRequest":{ "EventNotification":{ "EventDetails":"0123456789", "EventToNotify":"SaleWakeUp", "TimeStamp":"2019-11-15T10:16:10.000Z" }, "MessageHeader":{ "SaleID":"POSSystemID12345", "ProtocolVersion":"3.0", "MessageType":"Notification", "POIID":"V400m-324688179", "MessageClass":"Event", "MessageCategory":"Event", "DeviceID":"1517998561" } } } ``` ### UseAnotherCardForPreauth **Example notification** ```json { "SaleToPOIRequest":{ "EventNotification":{ "EventDetails":"paymentBrand=maestro", "EventToNotify":"UseAnotherCardForPreauth", "MaintenanceRequiredFlag":false, "TimeStamp":"2024-08-11T00:25:16.959Z" }, "MessageHeader":{ "SaleID":"POSSystemID12345", "ProtocolVersion":"3.0", "MessageType":"Notification", "POIID":"V400m-324688179", "MessageClass":"Event", "MessageCategory":"Event", "DeviceID":"1517998561" } } } ``` ## Asynchronous Terminal API responses If you use cloud communications and send your Terminal API requests to an [asynchronous endpoint](/point-of-sale/design-your-integration/choose-your-architecture/cloud#async), we send the Terminal API responses to your event notifications endpoint (provided you have set that up). These responses are exactly the same as the responses you'd receive in a Terminal API integration using local communications, or using cloud communications with a synchronous endpoint. The example below is a payment response. ```json { "SaleToPOIResponse": { "MessageHeader": { "MessageCategory": "Payment", "MessageClass": "Service", "MessageType": "Response", "POIID": "V400m-324688170", "ProtocolVersion": "3.0", "SaleID": "POSSystemID12345", "ServiceID": "200" }, "PaymentResponse": { "POIData": { "POIReconciliationID": "1000", "POITransactionID": { "TimeStamp": "2021-07-13T13:18:27.000Z", "TransactionID": "CWf3001626182307000.NC6HT9CRT65ZGN82" } }, "PaymentReceipt": [ { "DocumentQualifier": "CashierReceipt", ... "RequiredSignatureFlag": false }, { "DocumentQualifier": "CustomerReceipt", ... "RequiredSignatureFlag": false } ], "PaymentResult": { "AmountsResp": { "AuthorizedAmount": 45.08, "Currency": "EUR" }, "OnlineFlag": true, "PaymentAcquirerData": {...}, "PaymentInstrumentData": { "CardData": { "CardCountryCode": "826", "EntryMode": [ "Contactless" ], "MaskedPan": "541333 **** 9999", "PaymentBrand": "mc", "SensitiveCardData": { "CardSeqNumb": "33", "ExpiryDate": "0228" } }, "PaymentInstrumentType": "Card" } }, "Response": { "AdditionalResponse": "AID=A000000004101001&tid=47314497&transactionType=GOODS_SERVICES&...B&posAuthAmountValue=4508", "Result": "Success" }, "SaleData": { "SaleTransactionID": { "TimeStamp": "2021-07-13T13:18:27.846Z", "TransactionID": "772" } } } } } ``` ## Next steps [required](/point-of-sale/design-your-integration/terminal-api) [Terminal API fundamentals](/point-of-sale/design-your-integration/terminal-api) [Learn about our Terminal API.](/point-of-sale/design-your-integration/terminal-api) [Display notifications](/point-of-sale/design-your-integration/notifications/display-notifications) [Keep your staff informed of the progress of the transaction.](/point-of-sale/design-your-integration/notifications/display-notifications) [Platform-generated webhooks](/point-of-sale/design-your-integration/notifications/standard-notifications) [Receive standard webhooks generated by our platform.](/point-of-sale/design-your-integration/notifications/standard-notifications)