InStore Payment API Windows

  • Version: 2.08.04

Introduction

With the InStore Payment API, you can make payments easily and securely from a cash register or Windows kiosk using a wireless payment terminal.

This guide explains how to install the service on a Windows device and how to communicate with it via REST API.

Important Warnings

Please, follow these important warnings:

  1.  Do Not Copy Files Between PCs: Under no circumstances should you copy the files or folders associated with this software from one computer to another. Doing so may result in critical errors, data corruption, or irreversible malfunction of the system. This software has been configured specifically for the machine it was provided on. Transferring the files to another device without proper authorization or configuration is strictly prohibited and unsupported.
  2. Cloning or Imaging PCs: If a PC is cloned or imaged, you must uninstall the WECR service before creating the image, and reinstall it afterward on the new system. Failure to do so may result in configuration conflicts, service failures, or unexpected behavior. Each instance of the WECR service must be uniquely installed and registered on its respective machine.
  3. Only use the executable (.exe) file provided: Do not attempt to relocate, duplicate, or modify any of the supporting files or directories.

Failure to comply with these instructions may render the application inoperable and void any support or warranty agreements.

Files provided

With this guide, you get the file InStorePaymentApiInstallerVxx.xx.exe.

Very important:

InStorePaymentApiInstallerVxx.xx.exe needs to be executed with administrator mode:

  • Copy file InStorePaymentApiInstallerVxx.xx.exe on the folder you will execute it from.
  • Open/Use one of these options:
    • Use a Cmd with administrator “/s”.
    • Use powerShell (Terminal Administrator).

Install InStorePaymentApi by Windows Installer file

1. Double click on InStorePaymentApiInstallerVxx.xx.exe. or type on console, as shown on the picture:

2. Once you run this exe file installation it will be automatically install and execute the service.
3. You can follow the process on console, as shown on this image:

4. Console will close in 5 seconds after the process.
5. Finally, if all works fine, system generates a file CurrentVersion.txt including the version software that was installed.

Folder structure after the service installation

Once you run this exe file installation, you will find the following structure:

  • “Cer” folder: Signal R certificates.
  • db folder: private files.
  • dbt folder: private files.
  • “Static” folder: HTML content of the register web.
  • “Config.json” file: Communication configuration file.
  • “InStorePaymentApi.exe” file: Executable for InStorePaymentApi.
  • “InStorePaymentApiRegister”: Link to start the pairing process in a web browser (only needed to complete the pairing process in Windows).
  • “Nssm.exe” file: Windows services installer.
  • CurrentVersion.txt: Shows current version installed.
  • Installer.log file: log of installer.
  • Daemon.exe file: Windows services controller.

Folder structure after the service installation FIX IP

Once you run this exe file installation, you will find the following structure:

  • “Cer” folder: Signal R certificates.
  • “Config.json” file: Communication configuration file.
  • “InStorePaymentApi.exe” file: Executable for InStorePaymentApi.
  • “InStorePaymentApiRegister”: Link to start the pairing process in a web browser (only needed to complete the pairing process in Windows).
  • “Nssm.exe” file: Windows services installer.
  • CurrentVersion.txt: Shows current version installed.
  • Installer.log file: log of installer.
  • Daemon.exe file: Windows services controller.

Requirements

Here are the requirements for integration:

  • A Microsoft Windows device running Windows 7 (64-bit) or higher.
  • As the connection to the payment app is managed using this service over WiFi or 4G, an internet connection is required.
  • You must have the deviceID for the payment terminal that will receive the payment request.
  • It must be paired with the payment terminal. See pairing process.
  • The Android device must be running a version between Android 5.1 and Android 14 both inclusive.

Pairing process

Payment terminal and ECR could be paired. It’s mandatory in order to let the ECR manage the device id.

If you are working under a Proxy network, you should check this section.

There are two pairing processes:

  1. On the payment terminal, open “InStorePaymentApiRegister“. You will see the following screen:

On the PC, go to the installation folder and click on “InStorePaymentApiRegister“. The following website will open in your default web browser:

2. This is the workflow for pairing the terminal and the PC:

a. On the PC click the button to register the first time on the website.
b. On the terminal click on Scan and read the QR code from the website.
c. Finally, you will hear a beep on the terminal.
d. PAIRED OK will appear on the button when the terminal is paired.

1. On the payment terminal, open “InStorePaymentApiRegister“. You will see the following screen:

2. On the PC, go to the installation folder and click on “InStorePaymentApiRegister“. The following website will open in your default web browser. Copy the Device ID shown in the first step on the box shown on the following screenshot, then click on Register.

3. After a few seconds, the device will be paired, and the “Register” button will change to “Registered manually”.

How to set up proxy mode

1. Switch the settings mode in the config.json. file. Set “mode” from “B” to “S”.

				
					i. {
"port": "3000",
"key":"2",
"mode":"S",
"retries" :600
}

2. Proxy server side:

3. Manual pairing in proxy mode:

• Copy the “device ID” number for the terminal in the “Terminal name” text box on the website.
• Click Register.
• “Registered Manually” will appear when the registration has been completed correctly.

Go back to standard mode

If you want InStorePaymentApi to work in a network without Proxy technology (and you previously changed the mode to Proxy mode) you will need to go back to standard operation mode.

If the system needs to go back to normal mode (without proxy), follow these steps:

  • Stop InStorePaymentApi
  • Delete the folders db and dbt from the installation route: C:\Comercia\InStorePaymentApi
  • Switch the settings mode in the config.json. file. Set “mode” from “S” to “B”.
				
					i. {
"port": "3000",
"key":"2",
"mode":"B",
"retries": 600
}
  • Start InStorePaymentApi.
  • Pair again on QR mode terminal to ECR. Check this section.

Secure Sockets Layer (HTTPS) (Default mode)

If you want InStorePaymentApi works in SSL mode, please follow next instruction:

  • Add the next field in the config.json:
    • “SSL”:”True”
				
					i. {
"port": "3000",
"key":"2",
"mode":"B",
"SSL":"True",
"retries": 600
}
  • Use IngenicoPaymentServiceRegisterHttps to register devide in HTTPS mode.

Note: This version uses HTTPS mode by default. 

Pairing process using fixed IP

If you want the InStorePaymentApi to work with a fixed IP:

  • Set the terminal IP in ‘terminalIp’.
  • Set to F in ‘mode’.
				
					{
"port": "3000",
"url": "localhost",
"terminalIp": "192.168.55.105:3000",
"staticIptimeOut": 5,
"key":"3",
"mode":"F",
"SSL":"True",
"startTecnology": "pushy",
"loopsBefore": 2,
"timeStop": 240,
"retries": 600
}

Note: See Annex I for how to set a fixed IP in the Ingenico Android Terminal.

How to call HTTPS endpoints with custom certificate

In order to explain how secure HTTPS connections can be made, the following recommendations are proposed, using the Postman program as an example of an ECR box. 

The problem

When launching a call to an HTTP endpoint, normally Postman checks that the certificate of the server is valid and was generated by a known authority. When the server uses a custom certificate, this certificate was not generated by a known authority and, by default, the request is blocked showing the following message:

Error: Unable to get local issuer certificate

Which indicates that is not possible to associate with a known authority.

Solutions

This issue has two possible solutions:

1. Disable SSL certificate verification

This solution disables SSL certificate verification in Postman, allowing custom certificates. Follow these steps:

  1. Open Postman.
  2. Click on the gear icon in the top bar and then select Settings.
  3. In the General tab, uncheck the SSL certificate verification option.

2. Add the certificate as valid

For this solution, follow these steps:

  1. Add an entry to the Windows “hosts” file to resolve the DNS name set in the certificate to the terminal’s IP. This file is located in Windows at: “C:\Windows\System32\drivers\etc\hosts”.
  2. Add the following line:
    {device-ip} instorepaymentapi.globalpayments.es
    Replace {device-ip} with the IP of the Android device running the REST API.
  3. Ensure that the SSL certificate verification option is ENABLED:
    Go to “Settings” > “General” > “SSL certificate verification”.
  4. Click on the gear icon in the top bar and then select Settings.
  5. In the Certificates tab, enable the CA Certificates option.
  6. Add the certificate in PEM format.

Verify that the certificate has been resolved correctly by following these steps:

  1. Make the API call using the DNS name set in the “hosts” file.
  2. For example, to request the serial version:
    https://instorepaymentapi.globalpayments.es:3000/v1/getVersion
  3. If the certificate is resolved correctly, the secure connection icon (a circle with a padlock) will appear gray instead of red.

Install CA Certificates on Windows

For the API Rest application, it is necessary to install the certificates. In this section, we will explain step by step how to do this on Windows.

It is likely that, for some custom-developed applications, you will need to consult the developer to determine the correct path where these certificates should be installed.

This manual provides a step-by-step guide to install the certificates and verify that the installation was successful.

Prerequisites:

  • CGP v04.11.07 or above
  • instprepaymentapi
  • instprepaymentapirest
  • instprepaymentapisecurity
  • HAL

Step 1: Add your terminal’s IP address in the following path: C:\Windows\System32\drivers\etc

Open the “hosts” file as an administrator and add the IP address and corresponding URL.

Step 2: Open the following URL in your web browser to test the connection:

  • https://instorepaymentapi.globalpayments.es:3000/v1/getVersion

Step 3: Download the certificate “caroot.cert” and rename it to “caroot.cer“.

  • caroot.cer

Step 4: Double-click the file and follow the installation prompts to install it.

Screenshots for reference: 

Step 5: Open the following URL in your web browser to test the connection:

  • https://instorepaymentapi.globalpayments.es:3000/v1/getVersion

Solution for CORS request

If you get this message: “CORS requests have been successfully implemented and configured to allow secure cross-origin access to our resources.”

This is the explanation: “

  • CORS (Cross-Origin Resource Sharing) is a security feature implemented by browsers that restricts or allows web pages from one domain to make requests for resources on another domain. By configuring CORS headers correctly, we ensure that only authorized domains can access our resources, preventing potential security vulnerabilities.

Configuring client architecture (URLs and IPs to allow)

In order to ensure the correct operation of the InStorePaymentApi solution, it is recommended to keep in mind a list of certain URLs and IPs on the client’s router or access point, since these addresses may eventually be invoked by the different elements involved in the entire payment process: the InStorePaymentApi service, the POS itself, and so on.

Used by Android Devices

These are the addresses that should always be allowed in any architecture using the InStorePaymentApi solution on Android Devices:

URL / IP / Port
2.android.pool.ntp.org
asia.pool.ntp.org
http://connectivitycheck.gstatic.com
http://play.googleapis.com
http://www.googleapis.com/generate_204
http://developers.google.com
https://www.google.com
https://api.pushy.me/
supl.qxwz.com
https://info.izatcloud.net
https://gtp1.izatcloud.net:443/uds/v2 / /v3
http://*.izatcloud.net / https://*.izatcloud.net
time.xtracloud.net

Used by Windows Services

These are the addresses that should always be allowed in any architecture using the InStorePaymentApi solution on Windows Services:

URL / IP / Port
https://login.microsoftonline.com/
14508.ingest.sentry.io:443
.ingest.sentry.io:443
47.107.21.255:1900
https://ajax.aspnetcdn.com/ajax/jQuery/jquery-3.2.1.min.js

Custom or Shared Services

These are the addresses that should always be allowed in any architecture using the InStorePaymentApi solution:

URL / IP / Port
https://servicioterminalesautoinstalablesingenico.cestrack.net/…
https://ingenicoclientprostorage.z6.web.core.windows.net
https://apps.comerciacloud.com/api/
https://parameters.comerciacloud.com/parameters/api/
https://ticketdigital.in/
https://ingenicoapi.table.core.windows.net/
https://ingenicoapi.azurewebsites.net
https://ingenicoapi.service.signalr.net
https://tpvandroid.gmedia.ovh/
comswtfppzne02.trafficmanager.net:10020
51.138.108.206:10020
https://axyun.unimarspay.com:4443
https://axyun.ingenico-axcloud.net:8100/8101
http://firmwareota.unimarspay.com/aposfile/
http://axyun.ingenico-axcloud.net:81/aposFile/
https://slm-portal.icloud.ingenico.com/
tem-terminals-eu.icloud.ingenico.com:1883

QA IPs

These are the IPs that you should allow for QA: 

comswtfppzne03.trafficmanager.net:10020
https://tem-terminals-eu.preprod.icloud.ingenico.com 7037
https://tem-terminals-eu.preprod.icloud.ingenico.com 1883
https://tem-terminals-eu.preprod.icloud.ingenico.com 7022
https://cgp-terminalstest-apim-dev-dmz.azure-api.net/parameters/api/terminalparams
213.0.68.223:10011
35.233.8.200: 7046
comswtfprzwe07.trafficmanager.net:10020
comswtfprzwe03.trafficmanager.net:10020
20.73.126.179:10020
https://appspre.comerciacloud.com/api/raw/
Ingenicoapi-signalr-qa-as.azurewebsites.net

 

API definition

The REST API is defined in Swagger. Go there to verify the API. You can try it with the POSTMAN app or something similar on your Windows device. 

Extension of the Windows ECR scheme

This section expands the explanation of the cash register scheme with the Windows operating system, looking at the communication flows between components, in addition to the different timeouts that are handled, possible errors that the integrator must take into account, etc.

The solution that operates on Windows computers paired with Comercia payment terminals is what makes it easy for integrators who have developed a cash register solution to easily execute payments at the POS.

All that is needed is that both the Windows computer and the payment terminal have access to the Internet, and that both devices are paired with each other.

The architectural scheme that this solution follows is the following

This solution is made up of the following elements:

  • ECR connector: is an application installed on the cash register (Windows ECR) that implements an API-REST service to listen to calls from the integrator application.
  • InStorePaymentApi: is an application installed on the payment terminal (Android) that is constantly listening to PUSH or WEBSOCKETS type requests, originating from the ECR connector.
  • AzureCloud Connector: is the Azure cloud in charge of managing the database that records all transactions carried out in the payment terminal, as well as allowing the connection between ECR and terminals.
  • Pushy.me Server: it is a cloud service that allows the connection between ECR and terminals.

The connection and communication between ECR and terminals can be carried out through PUSH type notifications or through WEBSOCKETS through an Azure service called SignalR:

  • Pushy: is a cross-platform solution based on the MQTT protocol to be able to send push notifications using unique and auto-generated identifiers for each device, thus avoiding problems such as dynamic IPs.
  • SignalR: is a system of calls between devices and an Azure server made through websockets that allow any task that said server is capable of executing. In this way, communication channels can be established between different devices using identifiers, as well as registering the use of the API using a database.

By default, this solution uses the connection through PUSH notifications, but it is designed so that in the event of communication outages or service outages, it makes the technology change automatically, always having an operational communication channel.

Apart from the normal flow that transactions follow (red arrows), there is another use of the AzureCloud Connector which is to record all operations carried out on payment terminals (orange arrows). To do this, both the ECR connector and the InStorePaymentApi are automatically registered in said cloud, and it is the InStorePaymentApi that updates the database that is managed by the AzureCloud Connector at the end of each transaction.

The connections established by the terminal to the Pushy.me and Azure servers are made every time the terminal is turned on and are maintained indefinitely as long as there are no connection interruptions or any other errors. In the event that the terminal detects the closure of any of these connections, it will force registration again: this can occur, for example, when the terminal changes router when connected to a WiFi network, or when it changes mobile operator while roaming.

Basic transaction flow

A standard transaction, for example a sale, will be initiated in the integrator application. Through the API-REST service of the ECR connector, the type of transaction being requested will be informed, including the amount. An example of a sale for €10.00 would be:

				
					{ 
    "deviceId": "{{DeviceID}}", 
    "transactionId": "{{transactionId}}", 
    "paymentApp": "comercia", 
    "amount": 1000, 
    "currencyCode": "EUR", 
    "otherData": { 
        "printReceipt": 0 
    } 
}

Next, the ECR connector will send the request to the payment terminal through the communication channel activated at that moment: Pushy or SignalR. The communication channel will not be changed unless there is some type of problem such as the inability to connect to the servers, but if there are no errors the same channel will always be maintained.

Once the request is received in the payment terminal, the InStorePaymentApi application will launch the transaction in the Comercia C2.0 payment application through an AIDL connection. The payment application is identified as “My POS”, and is responsible for executing the entire payment process:

  • Card reading: in case of a reading error, it also makes retries until a correct one is obtained or the attempts are exhausted, and the transaction is canceled.
  • PIN request, if necessary.
  • Communication with the Comercia authorizing service: in the event of connection failures, it automatically carries out the pertinent cancellations, informing the Windows cash register of the result.
  • Shows the final result (transaction accepted or rejected) on the screen so that the client can check it.
    When the financial transaction has been completed in My POS, a response is prepared that travels back to the integrator’s application, using the same communication channel that was used in the original request.

This would be the flow of a standard transaction without failures:

Operation of the ECR connector

The API-REST service that implements the ECR connector on computers with a Windows operating system is constantly listening whenever it is running.

When it receives a request to carry out a transaction from the integrator application, the ECR connector transfers the request to the payment terminal and waits for a response with the final result of the transaction. It is at the moment of receiving said response that it informs the integrator application through API-REST.

While the ECR connector is waiting for the response from the payment terminal, it internally establishes maximum waiting times to mitigate waits in case of failures such as the network having gone down, or the payment terminal having been turned off unexpectedly. Errors of this type would cause the ECR connector to wait indefinitely for a response, so the integrator application would never know if the transaction has been accepted or denied, with the consequent damages.

The process that the ECR connector follows to avoid this situation is to ask the POS every 10 seconds if the payment process is still in progress. In the event that the transaction is still in process, and the payment terminal is still connected to the Internet, it will return to the ECR connector a response that everything is still correct, but there is still no final result. Keep in mind that a standard transaction can take about 30-40 seconds, and even more than 1 minute if the card PIN is required to be entered.

If the ECR connector does receive a response but it indicates that there is no transaction in progress, then a query will be made to the database to find out how the operation ended. In this way, a possible error when sending the response from the payment terminal is mitigated and it never reaches the Windows ECR.

If, on the other hand, the ECR connector does not receive a response in this situation, 2 more attempts will be made to know the status of the payment terminal. If no response is received from the payment terminal on the third attempt (this is 30 seconds after starting the transaction), a technology change will be made: from Pushy to SignalR or vice versa.

Once this change to the backup technology has been made, queries are made again to the payment terminal to find out its status. And if there are again 3 attempts without a response, the ECR connector will terminate the connection and return to the integrator application that the transaction has ended with a timeout error.

The following flow explains retries in case the payment terminal has been disconnected from the Internet:

Annex 1: How to set a fixed IP in the Ingenico Android Terminal

The purpose of this annex is to provide a guide on how to set a static IP for AXIUM terminals and APOS.

Step-by-Step Guide for AXIUM Terminals:

  1. Scroll the notification bar and click on Settings.
  2. Enter the settings password and click on “Accept”.
  3. Click on “Networt & internet”.
  4. Click on Wi-Fi.
  5. Select the preferred network from the available options.
  6. Select the pen icon in the top right.
  7. Click on Advanced options.
  8. Search for the DHCP protocol option and change it to Static IP.
  9. Enter the IP address and gateway.
  10. Click on save.
Comparte este documento
Tabla de Contenidos

Products

Sales

Tell us about your business so we can offer you the best solution.

Contact an expert
Contact an expert
Contact an expert
Contact an expert
Contact an expert

Technical Support

Already a client and need help? Contact us, we’re here for you.

Help

Partners

We work with the best partners for in-store and ecommerce solutions. Want to join us?

Join us

© Comercia Global Payments

Privacy policy
Exercising rights
Client information
Whistleblowing channel
Legal disclaimer
Cookies policy

Consulta la documentación de las distintas secciones de integraciones:

Comienza a integrar

undraw_add_to_cart_re_wrdo 1 (1) (1)

Plugins para CMS

Complementa la integración

SDKs

Métodos de pago

Herramientas

Addon Payments

Consulta la documentación de Addon Payments. Aquí tienes las distintas secciones:

Integraciones

Consultas frecuentes

Portal Backoffice

Cyberpac

We are currently working on the English version of the Cyberpac documentation. You can view the Spanish version using the buttons below:

Canales BackOffice Portal

Plugins integration

Custom integrations

POS integrated Payments

Create a solution that will help you automate processes. You can even add payment processes on physical terminals.

Payment Integrated with Android POS

Payment Integrated with Smartphone POS

POS Data sheets

Addon Payments

Comercia Global Payments has several integration options so you can choose the most efficient one for you.

Integrations

Frequently Asked Questions

BackOffice Portal

Consult the documentation of the different integrations sections:​

Start integration

undraw_add_to_cart_re_wrdo 1 (1) (1)

CMS Plugins

Complement your integration

SDKs

Payment Methods

Tools