Integration Options

Terminal Applications

Nexi SmartPOS Terminal Applications are standard Android applications integrated into the SmartPOS terminals. They utilize the device capabilities through Poynt Services.

Terminal Applications can be downloaded via the SmartPOS Marketplace. Nexi SmartPOS terminals leverage GoDaddy’s Poynt architecture which is based on:

• Custom Android OS supporting specific peripherals available on SmartPOS terminals
• One SDK supporting all Nexi devices/peripherals
• Open SmartPOS App Store giving developer full control of the App lifecycle

You may find the supporting documentation on the Terminal Apps page.

Cloud Applications

Nexi SmartPOS enables you to remotely access payment functionalities via the Payment Bridge APIs.

Supporting documentation can be found on the Cloud Applications page.

Enabling Cloud integration with Nexi SmartPOS requires coordination with Nexi in order to properly add the access credentials to the developer devices.

Payment Bridge API

Postman example callbacks received by the caller for a successfully completed transaction

The first callback is status RECEIVED in the request body. It is sent back from the terminal once the cloud message is received by the Payment Bridge app. That happens once the cloud message is delivered to the SmartPOS device.

REQUEST HEADERS
REQUEST BODY
  {referenceID: "94bf4cb9-e1b7-4565-849c-3c5e341635b3", status: "RECEIVED"}
RESPONSE HEADERS

In case the status RECEIVED is not delivered to the calling Cloud Application, it will assume that the request message is lost and the calling app should start an exception process. Examples of exception processes could be applying retry strategies or timeout exceptions.

REQUEST HEADERS
REQUEST BODY
  {referenceID: "94bf4cb9-e1b7-4565-849c-3c5e341635b3", status: "STARTED"}
RESPONSE HEADERS

The second callback is status STARTED in the request body. It is sent back from the terminal once the transaction starts. It corresponds to the moment in which the Payment Fragment is invoked.

{
   "adjustToAddCharges":false,
   "amount":200,
   "applicationIndex":-1,

Finally, the last callback is sent back when the Payment Fragment is closed. It will contain the entire bunch of information about the transaction processed. In the following example, we only show some of the information, not all.

transactions: [1]
  0: {…}
    action: "SALE"
    amounts: {…}

Terminal lifecycle

Cloud Applications manages the deviceId(s) of the connected SmartPOS. deviceId(s) refer to actual SmartPOS devices and these can change due to a new SmartPOS installation after a new shop activation or a terminal swap.

You can find the parameters that allow the lifecycle management of a terminal within the STOREDEVICE object.

When a new terminal is onboarded to a store, a new element with the following parameters is inserted within the STOREDEVICE array of the referenced STORE:

{
"createdAt": "2023-07-03T09:18:03Z",
"activatedAt": "2023-08-03T13:58:00Z",
"updatedAt": "2023-09-15T12:04:21Z",

Each STOREDEVICE is identified (not uniquely) by the externalTerminalId parameter that is also called TID or TML. The parameter consists of a numeric 8-digit code. This TID will later be associated with a physical terminal via the on-screen configuration process. It will be stored as deviceId (logical serial) and serialNumber (physical serial).

At this point, the first element to consider is the status of the device through the status parameter, which can take different values:

• CREATED - TID censored but never configured on a terminal
• ACTIVATED - TID activated at least once through the on-screen configuration process and associated with a deviceId and serialNumber
• REMOVED - TID retired

Should a device need to be replaced due to any issue, the new one will be configured via the standard process described above, and a new element in the array will be added. The old one may appear in two states, depending on how its decommissioning was handled:

• ACTIVATED
• REMOVED

In the case of the same externalTerminalId, to identify the most recent device, we need to refer to the activatedAt field and take the one with the most recent date.

To get the list of currently operational physical devices, two filters must be in place:

1. All STOREDEVICE should have the status ACTIVATED.
2. If there are multiple STOREDEVICE(s) with the same externalTerminalId, please consider only the one with the most recent date in the activatedAt parameter.

ECR-LAN & PosConnector/Scambio Importo

PosConnector, also known as Scambio Importo, is an application running on Poynt SmartPOS that can be downloaded from Poynt Marketplace. Its implemented logic receives and interprets messages by an external system according to the ECR-LAN Protocol which is running on the same local network (WiFi).

ECR (Electronic Cash Register) is a protocol that regulates the communication between an external system, like a PC, and an EFT-POS through a dedicated communication interface. In the case of a Poynt SmartPOS, that communication interface is Ethernet.

ECR may request Poynt SmartPOS to execute the following tasks:

• Status POS (to check if the terminal is operating)
• Purchase
• Void
• Pre-authorization
• Incremental
• Capture

The ECR protocol is based on the synchronous exchange of packets between the ECR system (that assumes the role of a server) and the terminal (that assumes the role of a client) in communication that is always initiated by the ECR system.

In order to let this Semi-Integration mechanism properly work, both the ECR system and the terminal must have a static IP address and port in a local network assigned to them. Even though PosConnector works mostly behind the scenes by receiving, interpreting and reacting to the messages sent by the ECR system, there are two processes that make it possible to see the static IP address of the terminal, reset the connection if any troubles occur, and set the TCP port according to the application that should be checked for incoming packets.

Further settings are available in the Setting option, as shown in the image below.