Event notifications

Receive terminal-generated event notifications in your POS app.

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, 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 or by using API calls. You then receive webhooks that include a Terminal API EventNotification and, if applicable, a Terminal API asynchronous SaleToPOIResponse. 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.

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.
Log in to your test Customer Area.
Switch to the merchant account, store, or terminal that you want to set up notifications for.
Go to In-person payments > Terminal settings > Integrations.
In the Terminal API section, select Decrypted.
Under Event URLs, select Add new.
Select the pencil icon next to the field that appears.
The Add URL dialog opens.
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.
Select Add URL.
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, you can use our Management 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.

To set up event notifications, you need to have the following role:

Management API—Terminal Advanced settings read and write

Proceed as follows:

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.
Optional. To see what display notification settings have already been configured, make a GET request to the /terminalSettings endpoint for the company account, merchant account, store or terminal, and check the nexo.eventUrls object.

When removing settings, you need to know the settings that will be inherited from the next higher level.

Make a PATCH request to the /terminalSettings endpoint on the company account, merchant account, store or terminal level.
In the request body, inside the 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 they 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 they want to receive notifications, in the format: http(s)://domain.com.
`username`	String	The username for authentication of the notifications.

When you receive the response, note that this returns the entire configuration at the level where you made the request.

Event notification types

Each notification contains an EventToNotify value. You can use this 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 initialised and is ready for transactions.
`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.

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

Terminal API fundamentals

Learn about our Terminal API.

Display notifications

Keep your staff informed of the progress of the transaction.

Standard webhooks

Receive standard webhooks generated by our platform.