Overview
This document describes how to connect to the eConduit Cloud service. The general principal is that the terminal makes a connection to the eConduit Cloud and keeps the connection open for commands to be sent to the terminal.
In order for us to know that we have received all of the necessary data, all commands sent to the server need to have 2 – 0x04 characters added to the end of the string. This includes registration, heartbeat and transaction responses.
Connection
The connection is a raw TCP socket that remains open at all times. This allows a channel to send transactions to the device and receive the response back. We have 2 production endpoints as some networks will block some outbound traffic. If a connection cannot be made to the primary endpoint, the secondary should be tried automatically. It is recommended that these 2 endpoints are configurable via the terminal management system where the file parameters and merchant host values are set.
If this connection is severed for any reason, the terminal needs to re-establish it as quick as possible.
Testing Endpoint
host: orddev1.blacklinepartners.com port: 9001
Production Endpoint Primary
host: dc.econduitapp.com port: 80
Production Endpoint Secondary
host: econduitapp.com port: 9001
Registration
When a terminal first starts up, the following json string should be sent to econduitapp.com port 9001 (this url and port need to be configurable in the download management system)
“Command”:”Register”,
“TerminalType”:”TerminalManufacturer”,
“TerminalModel”:”Model1″,
“TerminalID”:”29531204″, // This should be the device serial number
“SoftwareVersion”:”SomeProcessor v1.2″,
“AckHeartbeat”:”true”
}
0x04 0x04
Once sent, the server will respond with one of the following messages:
- OK-REGISTRATION (This is a success, anything else is a failure)
- FAILED-REGISTRATION (Generic catch all for any errors that may occur)
- FAILED-INVALID-TERMINAL-TYPE (Invalid terminal type in json data).
Once a successful registration has occurred, you should enter a waiting state for accepting terminal commands. If at any time the connection to the server is dropped, you will need to send a new registration string.
Heartbeat
The heartbeat command should be sent periodically when the terminal is idle to keep the connection alive, we recommend once per minute. The command is as follows:
{
“Command”:”TerminalHeartbeat”
}
0x04 0x04
If “AckHeartbeat” is set to true in the registration, here is what the response will look like:
{“Status”:”OK”} 0x04 0x04
Otherwise, no response is sent.
Transactions
When transactions are sent over the connection, they should be processed just as they are today, the communication format has not changed at all. The only change is on the response, you need to append 2 0x04 characters to the end of the string.
User Feedback
It is important for the end user to easily know if the terminal is connected to our cloud or not. When the terminal is in an idle state, it should show “POS Online” when the connection is active. When the connection is not active, it should show “POS Offline”. If possible, show the offline message in red so that it is easily visible.
Testing
We will provide you with a url to send test transactions to the terminal. When testing, you should verify that when a connection is lost to us, it is reestablished as quickly as possible. Possible reasons for a connection lost are
- Loss of internet
- Loss of wifi
- Loss of network (i.e. cable unplugged)