Desktop – ECR Connector

The HiPay Desktop Connector allows you to process in store payments and create a transaction on HiPay Console.

The payment workflow is the following one:

      1. The point-of-sale software sends a request payment to the Desktop Connector.

      2. Desktop Connector initializes the payment on the POS Terminal e.g the amount is displayed on the screen and the customer should process the payment.

      3. POS Terminal sends the result payment to the Desktop Connector in its format.

      4. Desktop Connector sends the result to the point-of-sale software with a custom object.

      5. Transaction request is sent to HiPay’s server

Installation

Initialization

Payment Request

The Desktop ECR Connector allows you to make a payment, followed by an order if the payment succeed.

URL

http://localhost:{LOCAL_PORT}

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

AUTH

All requests to the 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’)

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 
transaction_typeType of transaction to be processedEnumDebitDebit
force_authorizationWhether the authorization should be forced or not. Overwrites the authorizationThreshold parameter to enable authorizationBoolean False
currencyISO 4217 alpha currency code (More information)EnumEUREUR
order_idOrder number of your request payment. If you don’t send an identifier, we will generated it for youStringe.g. “Order_12345” 
cart**Cart object (More information)Cart– 
customerCustomer’s information object (id, firstName, lastName, email)Customer– 
custom_dataCustom data (only value type Bool / Int / Float / String are accepted)Dictionary– 
{
  "amount": "10,23",
  "currency": "string",
  "order_id": "Order_12345",
  "transation_type": "Debit",
  "force_authorization": false,
  "cart": {
    "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]"
  },
  "custom_data": {
    "shop": "Opera",
    "vendor": "Mario",
    "newCustomer": true,
    "event": 42
  }
}

Payment Response

After the transaction has been processed through HiPay’s servers, you will receive a response containing the following information. The response is given synchronously following the request.

Variable nameDescriptionTypeValues
paymentStatusStatus received from the TPE regarding the payment.Enum

SUCCESS

FAILURE

notificationHipaySentIndicates whether Hipay has been notified of the transactionBooleane.g. false
numberOfNotificationSentIndicates the number of notifications sent to Hipay. Sometimes this value can be 2 in order to ensure the financial reconciliation.Numerice.g. 1
errorCodeError codeStringe.g. : “1003”
errorDescriptionError descriptionStringe.g. : “The network is unavailable”
amountAmount of the transactionFloate.g. : 98.80
currencyISO 4217 alpha currency codeEnume.g. : .EUR
orderIdOrder numberStringe.g. : “order_12345”
customerPersonal information of the customerCustomer 
{
  "paymentStatus": "SUCCESS",
  "notificationHipaySent": true,
  "numberOfNotificationSent": 1,
  "amount": "10,23",
  "currency": "string",
  "orderId": "Order_12345",
  "transationType": "Debit",
  "forceAuthorization": false,
  "cart": {},
  "customer": {},
  "customData": {}
}

Maintenance

The desktop connector has some additional features that allow you to handle the maintenance. The endpoints that you can use are the following ones.

GET /version

Get current version of terminal manager application.

No parameters on the request. Response:

{
  "version": "0.0.0-concertv2-winserver2003_64"
}

GET /config

Get serial number of hardware terminal

No parameters on the request. Response:

{
  "deviceId": "00000012345678"
}

GET /stop

Stop terminal manager server.

No parameters on the request. Response:

{
  "message": "TP-Manager stopped",
  "stopped": false
}