Take paymentsPayroc CloudConfigure your deviceIngenico

Ingenico - Linux

View as MarkdownOpen in Claude

In this configuration, your Ingenico device communicates with your Linux host machine through the Payroc Cloud middleware. To ensure your POS can communicate with your Ingenico device, you need to configure your Linux host machine.

Integration steps

  1. Prepare your host machine for configuration.
  2. Configure the native libraries.
  3. Configure the payconfig.xml file.
  4. Run the middleware.

Before you begin

Your host machine must have Java 8 or later installed.

Step 1. Prepare your host machine for configuration

To download the Payroc Cloud middleware and connect your payment device to your host machine, complete the following steps:

  1. Connect your payment device to a USB port on your host machine.
  2. Go to our Github repository, and then download Payroc Cloud middleware from the release files.
    • If your host machine has Java 8 up to Java 16 installed, download version 1.6.76.
    • If your host machine has Java 17 or later installed, download version 1.6.78+.
  3. Extract the files from the zipped folder.

Step 2. Configure native libraries

You need to copy the libraries that match your operating system into the middleware root folder so the middleware can load them when it starts. To do this, complete the following steps:

  1. Open the folder that you extracted the Payroc Cloud middleware to.
  2. Go to the folder that contains the library that you want to use, for example, to use 64-bit Linux with Ingenico, go to libs > ingenico > nativeLibsLinux > 64_bit.
  3. Copy the contents of the folder into the root folder.
  4. Create a new file in /etc/udev/rules.d and name it usb.rules.
  5. Add the following contents to the file: SUBSYSTEM==\"usb\", MODE=\"0666\".

Step 3. Configure the payconfig.xml file

The payconfig.xml file defines how the middleware communicates with your Ingenico device and our gateway, including:

  • Which Payroc account and integration you are working with, for example, you send your API key to authenticate your requests.
  • Which payment device the middleware is communicating with, for example, you send the value for the port that your Ingenico device is connected to on your host machine.
  • How your Ingenico device should behave in transactions, for example, you indicate if the device should accept keyed transaction details.

Use the following values to configure your payconfig.xml file:

FieldValue
apiKeyEnter your Payroc App API key.
integrationIdEnter your integrationId.
terminalIdEnter your processingTerminalId.
deviceTypeIndicates the type of payment device you are using. Enter INGENICO.
sdkModeIndicates the SDK mode. Enter one of the following values:
– LIVE - Production mode
– TEST - Test environment
– DEV - Developer mode
logLevelIndicates the logging level for the SDK. Enter one of the following values:
– LEVEL_FUL - Verbose
– LEVEL_INFO - Informational messages
– LEVEL_ERROR - Errors only
– LEVEL_NONE - Disables logging
portNameIndicates the Serial/COM port name of the USB port that you connected the Ingenico device to.
emvTypeIndicates the EMV processing type you want the device to support. Enter one of the following values:
– STANDARD - Standard EMV processing.
– QUICK_CHIP - Faster EMV transaction flow.
inputMethodIndicates the EMV processing type you want the device to support. Enter one of the following values:
– SWIPE_OR_INSERT_OR_TAP_OR_KEYED - Cardholder can swipe, insert, tap, or key in their card number manually.
– SWIPE_OR_INSERT_OR_TAP - Cardholder can swipe, insert, or tap their card.
– SWIPE_OR_INSERT - Cardholder can swipe or insert their card.
debitAIDPreferenceIndicates the Debit Application Identifier (AID). Applies to dual banded cards. The value must be one of the following:
–PREFER_GLOBAL_DEBIT_AID - Prioritize global AID.
–PREFER_US_COMMON_DEBIT_AID - Prioritize U.S. debit AID.
–APPLICATION_SELECTION - Cardholder can choose between debit or credit.
disableOnDeviceSignatureFor Ingenico 5000 and 7000 devices, enter one of the following values:
–true - Device does not support cardholder signatures.
–false - Device supports cardholder signatures.

For other Ingenico devices, do not edit this value.
enableDeviceLogsIndicates whether the device collects debug logs. Enter one of the following values:
– true - Device collects debug logs.
– false - Device does not collect debug logs.

Step 4. Run the middleware

To run the middleware, complete the following steps:

  1. Run the following command to make the start.sh file executable: $chmod +x start-ingenico.sh

  2. Run the following script to start the middleware: $ ./start-ingenico.sh

This establishes communication between your host machine, your Ingenico device, and our gateway.

After the middleware starts, the logs display the serial number of your Ingenico device. You need this serial number to send transaction requests so the gateway can route the instructions to the correct device.

Next steps

To program your POS to send instructions to your Ingenico device, go to Run a sale.