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 generates 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, make sure you have a server with:

• 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.

Step 2: Set up notifications in your Customer Area

The next step is to enter your server's details in your Customer Area, and select additional information that you want 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, select Add.
4. In the Transport section:
   • Enter your server's URL. Make sure that this is a public URL.
   • Enter your server's SSL (TLS) Version.
   • Select the Active check box.
5. 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.
6. In the Additional settings section, turn on Event notification.
7. Select Test Configuration and verify that the notification was received at your endpoint.
8. If your endpoint received the notification, select Save Configuration.

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

Event notification types

Each notification contains an EventToNotify value. You can use this to present a message on your cash register informing your store 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 initialised and is ready for transactions.
Reject	A request was rejected. An explanation of the error should be provided in the EventDetails element.
SaleWakeUp	The terminal is initiating a payment request. The EventDetails element contains the reference number that was entered on the terminal.

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

SaleWakeUp

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

See also