Event notifications

From time to time, one of your Adyen terminals will encounter an issue, or need to perform maintenance. When this happens, the terminal will generate an event notification. You can optionally present this on your cash register to inform your store staff of the terminal's availability and state.

Here we describe how you expose an endpoint on your server, and set up event notifications. Your server will then receive webhooks that include an EventToNotify value. This indicates the state of the terminal, and can be used to present a message on your cash register.

We also provide a list of possible EventToNotify values, and examples of each.

Set up event notifications

Step 1: Expose an endpoint on your server

Event notifications are sent as HTTP callbacks (webhooks) to an endpoint on your server. To receive notifications, you need a server that has:

• An endpoint that can receive a JSON call.
• An open TCP port for HTTP traffic (443, 8443, or 8843).

  For testing, you can also use an HTTP port (80, 8080, or 8888).

• A username and password for basic authentication.

Next, enter the details of this endpoint in your Customer Area.

Step 2: Set up notifications in your Customer Area

Enter your server's details, and select additional information that you wish to receive in notifications. You can configure notifications either at company or merchant account level.

1. Log in to your Customer Area. To configure notifications at merchant level, switch to your merchant account.
2. Go to Account > Server communication.
3. Next to Terminal API Notification, click Add.
4. Under Transport, enter your server's:
   • URL. Make sure that this is a public URL.
   • SSL (TLS) Version.
5. Check the Active checkbox.
6. In the Authentication section, enter your server's username and password for basic authentication.
   We include these details in the header of the notification request to authenticate with your server.
7. Under Additional settings:
   • Turn on Event notification.
8. Click Test Configuration, to test whether the notification was received at your endpoint.
9. If your endpoint received the notification, click Save Configuration.

Event notifications will now be sent to the endpoint you specified.

Event notification types

Each notifications contains an EventToNotify value. Use this to present a message on your cash register informing your store staff of the terminal's state.

Name	Description
Shutdown	The terminal is shutting down. For an example of this notification, see Shutdown
BeginMaintenance	Terminal maintenance is beginning. For an example of this notification, see BeginMaintenance
EndMaintenance	Terminal maintenance is ending. For an example of this notification, see EndMaintenance
OutOfOrder	The terminal is out of order. For an example of this notification, see OutOfOrder
Initialised	The terminal has been initialised and is ready for transactions. For an example of this notification, see Initialised
Reject	A message request is rejected. An error explanation and the message in error have to be put in the EventDetails element. For an example of this notification, see Reject

Examples of event notifications are provided below.

Examples

Shutdown

{
   "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

{
   "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

{
   "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

{
   "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

{
   "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"
      }
   }
}

Reject

{
   "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"
      }
   }
}