From time to time, one of your payment 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.
- For live environments: An open TCP port for HTTPS traffic (443, 8443, or 8843) with TLS 1.2.
- For testing environments: An open TCP port for HTTP traffic (80, 8080, or 8888) or HTTPS traffic (448, 8443, or 8843) with TLS 1.2.
- 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.
- Log in to your Customer Area. To configure notifications at merchant level, switch to your merchant account.
- Go to Account > Server communication.
- Next to Terminal API Notification, select Add.
- 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.
- 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. - In the Additional settings section, turn on Event notification.
- Select Test Configuration and verify that the notification was received at your endpoint.
- If your endpoint received the notification, select Save Configuration.
Event notifications will now be sent to the endpoint you specified.
Step 3: Accept notifications
To ensure that your server is properly accepting notifications, we require you to acknowledge every notification of any type with an [accepted] response.
If we don't receive this response within 10 seconds, for example because your server is down, all notifications to your endpoint will be queued and retried. For more information, refer to Queued notifications.
When your server receives a notification:
- Store the notification in your database.
- Acknowledge the notification with the following response:
[accepted] - Apply your business logic.
Make sure that you acknowledge the notification before applying any business logic, because a breakage in your business logic could otherwise prevent important updates from reaching your system.
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"
}
}
}