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 on your cash register to inform your store staff of the terminal's availability and state.
To receive event notifications and, if applicable, asynchronous Terminal API responses, you need to expose an endpoint on your server, and accept event notifications.
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. Adyen requires you to use HTTPS endpoints with TLSv1.2. 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 TLSv1.2.
- For testing environments: An open TCP port for HTTP traffic (80, 8080, or 8888) or HTTPS traffic (448, 8443, or 8843) with TLSv1.2.
- A username and password for basic authentication.
Step 2: 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.
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.
Step 3: 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 Developers > Webhooks.
- In the upper-right corner, select the + Webhook button.
- Next to Terminal API details, select Add.
- In the Transport section, enter your server's:
- URL. Make sure that this is a public URL.
- SSL (TLS) Version. Select TLSv1.2.
- Select the Active checkbox.
- 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. If you are using cloud communications with an asynchronous result, the Terminal API responses are also sent to this endpoint.
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.
Event notification 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"
}
}
}Asynchronous Terminal API responses
If you use cloud communications and send your Terminal API requests to an asynchronous endpoint, 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.
{
"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.9915402177165382"
}
},
"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"
}
}
}
}
}