Display notifications

During a transaction or tender, the payment terminal generates display notifications. You can show these in your POS app to keep your staff up-to-date on the progress of the tender. For example, whether the customer has selected Dynamic Currency Conversion, or finished entering their PIN.

Here we describe how to set up display notifications. You can do this in your Customer Area or by using API calls. You then receive webhooks that include a Terminal API DisplayRequest from the terminal. This has an event indicating the progress of the transaction, or the result of the transaction. You can use this information to show a message in your POS app.

We also provide an overview of display notification types, and examples of each.

Set up display notifications in the Customer Area

To get display notifications, 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.

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

2. Log in to your Customer Area.

3. Switch to the merchant account, store, or terminal that you want to set up notifications for.

4. Go to In-person payments > Terminal settings > Integrations.

5. In the Terminal API section, select Decrypted.

6. Under Display URLs, select Add new.

7. Select the pencil icon next to the field that appears.
   The Add URL dialog opens.

8. Enter the details:

   • URL: the URL of the endpoint where you want to receive display 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.

9. Select Add URL.

10. Select Save.

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

Set up display 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 display notifications, you need to have the following role:

• Management API - Terminal settings Advanced read and write

Proceed as follows:

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

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

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

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

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

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

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

Display notification types

A display notification is a DisplayRequest sent from the terminal. It includes a ReferenceID field with either:

• event: the interaction between the terminal and the customer.
• Result: the outcome of the transaction.

Use the ReferenceID to show a message to your staff, informing them of the progress of the transaction.

The main display notification types are:

Examples of display notifications are provided below.

Examples

TENDER_CREATED

CARD_INSERTED

CARD_SWIPED

WAIT_FOR_APP_SELECTION

APPLICATION_SELECTED

WAIT_FOR_PIN

PIN_ENTERED

PRINT_RECEIPT

CARD_REMOVED

TENDER_FINAL

BALANCE_QUERY_STARTED

GRATUITY_ENTERED

LOAD_STARTED

PROVIDE_CARD_DETAILS