Kiosk – Unattended Terminal Connector

The main goal of the Unattended ECR Connector is to create a transaction from your kiosk using an unattended terminal.

Workflow

      1. The kiosk software sends a request payment to the ECR Connector.

      2. The ECR Connector initializes the payment on the unattended Terminal e.g the amount is displayed on the screen and the customer should process the payment. 

      3. The Unattended Terminal sends the payment result to the ECR Connector.

      4. The ECR Connector sends the result to the kiosk software.

      5. The Transaction request is sent to HiPay’s server

Requirements

Installation

Initialization

Windows

Identify the port used by the terminal

If you don’t know the local port used by the unattended terminal, please start your terminal and connect it to the windows computer who runs the ECR connector.

Then, download and install the USBDeview software from this URL. When launching the USBDeview software, you can identify the local port in the Drive letter column from a device name that becomes green when you plug the terminal.

In this example the local port is COM8

Fill in the setup file

You have to set the setup file named config.txt which is located into the data directory. The different information needed for the setup file are the following ones.

Variable nameDescriptionTypeValue example
SERIAL_PORTSerial port used by the terminalStringCOM8
LOCAL_PORTThe port used by the connector to handle the local APIInteger8080
TERMINAL_MANAGER_LOGINThe login used to secure the access to the local API with Basic AuthStringlog
TERMINAL_MANAGER_PWDThe password used to secure the access to the local API with Basic AuthStringpwd
HIPAY_LOGINPublic HiPay API username used by authenticationString99999999.stage-secure-gateway.hipay-tpp.com
HIPAY_PWDPublic HiPay API password used by authenticationStringTest_XXXXXXXXXXXXXXXXXXXXXXXX
UPDATE_TIMEConnector update time with hh:mm formatTime04:00

Manual ECR connector launch

In order to check if the configuration is well done and everything works fine, you have to launch the ECR connector manually by executing program launch.cmd located on delivery files at the root directory.

The following program is started:

      • tp-manager: who’s role is to drive device,
      • supervisor: who’s role is to communicate between tp-manager and HiPay.

If one of these programs stop few seconds after started, it occurs one failure during the program start. Please check again the previous step to modify the configuration.

Kill manually tp-manager and supervisor before to start next step.

Automate the ECR connector launch

You can automate the ECR connector launch from the computer who runs the ECR connector following the next steps:

      1. Click on Start menu > Windows Administrative Tools > Task Scheduler.

      2. Click on Action > Create Task

      3. Once the Create Task screen appears, in the “Name” field, give the task name : Unattended ECR Connector.

      4. Select the option “Run whether user is logged on or not”.

      5. In the “Configure for” drop down menu, select “Windows 10.

6. Go to the “Triggers” tab and select “New…”.

7. Select “Daily” Settings and let “Recur every” 1 days

8. In advanced settings, enable “Repeat task every” and select in the drop down menu “5 minutes”

9. Go to the “Actions” Tab and select “New …”.

10. Select “Browse…“ and find the program “always-up” (located on delivery files at the root directory) and click on the button “Open” to select this file to be scheduled for this task.

11. Select “OK“.

12. Go to the “Conditions” Tab.

13. Enable “Wake the computer to run this task” 

14. Disable “Stop if the computer switches to battery power”

15. Then go to the “General” tab and Click on “OK”

16. The “Task Scheduler” login screen will appear.

17. Enter your password to enable the program to start on your computer and click on “Ok”.

The new task “Unattended ECR Connector” is ready and will start in few minutes.

Linux

Identify the port used by the terminal

If you don’t know the local port used by the unattended terminal, please compare 2 devices lists:

      • before connecting the terminal (cmd> ls /dev)
      • after connecting the terminal (cmd> ls /dev)

The new device that appears in the second list is the unattended terminal device.

Example : /dev/ttyUSB0

Grant the access to the port used by the terminal

You need to add the dialout group to the port used by the terminal in order to access this port. Type this unix command (and replace USER by the login used to launch this connector software) :

sudo usermod -a -G dialout USER

 Fill in the setup file

You have to set the setup file named config.txt which is located into the data directory. Here you have the different data of the file.

Variable nameDescriptionTypeValue example
SERIAL_PORTSerial port used by the terminalString/dev/ttyUSB0
LOCAL_PORTThe port used by the connector to handle the local APIInteger8080
TERMINAL_MANAGER_LOGINThe login used to secure the access to the local API with Basic AuthStringlog
TERMINAL_MANAGER_PWDThe password used to secure the access to the local API with Basic AuthStringpwd
HIPAY_LOGINPublic HiPay API username used by authenticationString99999999.stage-secure-gateway.hipay-tpp.com
HIPAY_PWDPublic HiPay API password used by authenticationStringTest_XXXXXXXXXXXXXXXXXXXXXXXX
UPDATE_TIMEConnector update time with hh:mm formatTime04:00

Manual connector launch

In order to check if the configuration is well done and everything works, you have to launch the connector manually by executing program launch.sh located on delivery files at the root directory.

The following program is started:

        • tp-manager: who’s role is to drive device,
        • supervisor: who’s role is to communicate between tp-manager and HiPay.

If one of these programs stop few seconds after started, it occurs one failure during the program start. Please check again the previous step to modify the configuration.

Kill manually tp-manager and supervisor before to start next step.

  • Automate connector launch

  • From your computer who run the connector, add a new line into the cron to schedule a new task that run every 2 minutes via the command crontab -e (and replace the directory /home/user/ecr/ by your own directory where you  have installed the connector software) :

  • */2 * * * * /home/user/ecr/always-up.sh

Request

The Unattended ECR Connector allows you to:

      • make a payment which is following by an order if the payment succeed,

      • manage terminal with terminal maintenance call.

URL

The Unattended ECR Connector URL is:

http://localhost:{LOCAL_PORT}

Following the previous configuration example, the URL would be http://localhost:8080

Authentication

All requests to the Unattended ECR Connector require identification through HTTP Basic Authentication. Your API credentials can be found in the “Integration section” of your HiPay Enterprise back office. Most HTTP clients (including web browsers) have built-in support for HTTP basic authentication. If not, the following header must be included in all HTTP requests.

Authorization: Basic base64(‘API login’)

The response is given synchronously following the request.

REQUEST

Variable nameDescriptionTypeValuesDefault
amount*Total order amount, calculated as the sum of purchased items, plus shipping fees (if present), plus tax fees (if present).Floate.g. 9.99 
orderId*Order number of your request payment. If you don’t send an identifier, we will generated it for youStringe.g. “Order_12345” 
currencyISO 4217 alpha currency code (More information)EnumEUREUR
basket**Cart object (More information)Cart– 
customerCustomer’s information object (id, firstName, lastName, email)Customer– 
customDataCustom data (only value type Bool / Int / Float / String are accepted)Dictionary– 

   *  Mandatory

  ** If the cart content is not correctly fulfilled or doesn’t match the total amount of the order, the order will be created with an empty cart.

{
  "amount": 100,
  "orderId": "Order_12345",
  "currency": "EUR",
  "basket": {
    "european_article_numbering": 4711892728946,
    "product_reference": "NF-a1690",
    "type": "good",
    "quantity": 1,
    "name": "My first product",
    "unit_price": 8.99,
    "tax_rate": 0,
    "discount": 0,
    "total_amount": 8.99
  },
  "customer": {
    "id": 283749291,
    "firstname": "John",
    "lastname": "Doe",
    "email": "[email protected]"
  },
  "customData": {
    "shop": "Opera",
    "vendor": "Mario",
    "newCustomer": true,
    "event": 42
  }
}

Payment Response

Here you can find an exemple of a 200 – OK Response.

[
  {
    "status": "Success",
    "error": null,
    "receipt": {
      "ticketHeader": "                    ",
      "localDate": "030420",
      "localTime": "083011",
      "acceptor": "HIPAY                                 92HIPAY             ",
      "transactionType": "01",
      "contractNumber": "123456",
      "SIRET": "12345678901234",
      "activity": "5039",
      "paymentType": "46",
      "siteType": "        ",
      "primaryAccountNumber": "123456XXXXXX7890",
      "TASA": "2046",
      "cardAppExpiry": "221031",
      "serviceCode": "   ",
      "crypto": "1234567898765434",
      "currencyNumCode": "978",
      "acceptationSystemNum": "001",
      "transactionNumber": "000001",
      "transactionFileNumber": "000006",
      "readingMode": "C",
      "authorizationNumber": "136967",
      "forceCode": " ",
      "amount": "00000899",
      "currencyAlphaCode": "EUR",
      "currencyFractionPart": "2",
      "counterValueAmount": "00005897",
      "counterValueCurrencyAlphaCode": "FRF",
      "counterValueCurrencyFractionPart": "2",
      "inclusiveAmount": "00000899",
      "ticketFooter": "                                       ",
      "AID": "A0000000041010  ",
      "label": "Mastercard      "
    },
    "ticket": "CARTE BANCAIRE|A0000000041010Mastercard|LE 28/11/19 A 11:06:17|HIPAY |92HIPAY |123456 39033123454322345|XXXXXXXXXXXX1234   1234567899765|001 000001 03 C |@|NO AUTO:122603|MONTANT REEL:1,00 EUR|MONTANT ESTIME:8,99 EUR|DEBIT|TICKET CLIENT A CONSERVER||",
    "amount": 100,
    "currency": "EUR",
    "orderId": "Order_12345",
    "basket": {
      "european_article_numbering": 4711892728946,
      "product_reference": "NF-a1690",
      "type": "good",
      "quantity": 1,
      "name": "My first product",
      "unit_price": 8.99,
      "tax_rate": 0,
      "discount": 0,
      "total_amount": 8.99
    },
    "customer": {
      "id": 283749291,
      "firstname": "John",
      "lastname": "Doe",
      "email": "[email protected]"
    },
    "customData": {
      "shop": "Opera",
      "vendor": "Mario",
      "newCustomer": true,
      "event": 42
    },
    "notificationHipaySent": true
  }
]

Maintenance

In addition to the payment, the unattended terminal connector allows you to perform the maintenance operations below.

GET /cancel

Cancel current transaction.

GET /stop

Stop the terminal manager server.

GET /reset

Ask terminal to male a reboot.

GET /version

Get the current version of the terminal manager application.

[
  {
    "version": "0.0.0-tpa-winserver2003_64",
    "type": "tpa",
    "os": "winserver2003_64"
  }
]

GET /config

Get serial number of hardware terminal.

[
  {
    "version": "0.0.0-tpa-winserver2003_64",
    "type": "tpa",
    "os": "winserver2003_64"
  }
]

GET /tlc

 Telecollection. Data capture request.

[
  {
    "NbApp": "1",
    "App": [
      {
        "Name": "CB EMV",
        "Status": "0"
      }
    ]
  }
]

GET /check

Check the hardware terminal status.

[
  {
    "cr": "0",
    "card": "0",
    "call": "0",
    "periph": "0"
  }
]