API Reference

Semi Integration Support via USB

Introduction

This guide explains how to establish USB-based communication between Linux POS terminals (VL100Pro, VL100, VL110, VP100 and VL300 Standalone) and third-party software applications. It enables seamless transaction exchange, allowing external systems to interact with Valor devices for real-time payment processing.

Objective & scope

The objective of this guide is to assist developers and integrators in enabling USB communication between Valor Linux POS terminals and external third-party software.

This guide covers:

  • System prerequisites and configuration requirements.
  • Enabling USB mode through the Valor portal.
  • Preparing the device for Valor Connect listening mode through USB.
  • Formatting and sending transaction payloads.
  • Parsing response data from the device.
  • Testing integration using code examples in Python, Node.js, and C.
  • The scope is limited to USB-based semi-integration on Linux systems for supported Valor terminals running application version 3.0.32 or higher.

Prerequisites

  1. Linux system with USB port available.
  2. Valor Portal access with permission to edit device parameters.
  3. EPI with version 3.0.32 or higher assigned.
  4. USB cable to connect terminal to the computer.
  5. Your device com port.
  6. Reference document: Valor POS Integration.pdf__1.1.4 (for complete list of API payloads).
  7. USB Drivers link for VP Linux device

Benefits

  • Enables USB-based communication between Valor POS terminals and third-party desktop applications.
  • Supports real-time transaction exchange using JSON-formatted payloads.
  • Works across multiple programming languages with sample code in Python, Node.js, and C.
  • Configurable via the Valor Portal with minimal setup effort.
  • Ensures structured and secure data transmission using framed messages.

Enabling Valor Connect (USB Mode)

  1. Login to the Valor Portal.
  2. Navigate to the Device Management module and locate the targeted device.
  3. Select the Vertical Ellipsis on the right end of the Device entry.
  4. Select Edit Parameters and navigate to the Terminal & Transaction tab.
  5. Open the Valor Connect sub-tab and enable Connection Type.
  6. Set the Connection Mode to USB and select Save from the top-right corner.

Preparing the Device for USB Communication

  1. Connect your POS terminal to the computer through USB.
  2. Perform a Parameter Download on the terminal and wait for the USB Listening screen.

If the Listening screen does not appear:

  • Select Star icon on the bottom pane of the home screen.
  • Navigate and select Start USB.

Once in USB Listening mode, the device is ready for integration.

Setup to Enable USB Mode in VP100 POS

Step 1: Unzip the USB Driver

  1. Locate the downloaded driver package (e.g., Usb_Driver.zip).
  2. Right-click on Usb_Driver.zip and select 'Extract All' or use any unzip tool.

Step 2: Install the Driver

  1. Open the extracted folder.
  2. Double-click the application named DriverInstall.exe or Driver Install (Application type).

Fig 01: Extracted Folder to Install Driver.

  1. A command window will appear, showing the installation progress.

Note: The interface will display installation messages during setup.

Fig 02: Information screen on the Installation Progress

Step 4: Finish Installation

  1. Press any key to close the installation window.
  2. Your VP100 POS device is now ready to use the USB port.

Communication Protocol

Request Format

  • All communication is framed with at the start and at the end.
  • Payload is JSON-formatted.

Sample Request Payload

<STX>
{ 
"TRAN_MODE":"1", 
"TRAN_CODE":"1",    
"AMOUNT":"450000",    
"TIP_ENTRY":"1",    
"TIP_EDITABLE":"1",    
"ONLINETIP_CONFIRM":"1",    
"SIGNATURE":"1",    
"PAPER_RECEIPT":"0",    
"MOBILE_ENTRY":"1" 
}
<ETX>

Receiving Response

For every executed transaction, the terminal sends back a response in the below format

<STX>
{response JSON}
<ETX>

Note:

  • Strip the and markers to parse the JSON payload.
  • The terminal also sends an acknowledgement for every successfully received payload.

Sample Response Payload

<STX>
{    
"STATE":"0",    
"EPI":"2320047546",    
"SERIAL_NO":"125214118808",    
"TRAN_TYPE":"Cash",    
"TRAN_METHOD":"Cash Sale",    
"TXN_ID":"223064651659",    
"AMOUNT":"450000",    
"PARTIAL":"0",    
"SURCHARGE_AMOUNT":"4500",    
"ENTRY_MODE":"MANUAL",    
"ENTRY_TYPE":" ",    
"RRN":"223064651659",    
"CODE":"000000",    
"DATE":"28072025 03:48:17",    
"TRAN_NO":"2",    
"BATCH_NO":"2",    
"ISSUER":"CASH",    
"TOTAL_AMOUNT":"454500",    
"STAN_ID":"3" 
}
<ETX>

Testing with Sample Code

Below are example snippets for sending a payload over USB and reading the response.

Note: (Replace /dev/ttyUSB0 with the actual USB device path.)

Example Sample Code (Phyton, C, JavaScript)

import serial ser = serial.Serial('/dev/ttyUSB0', 9600, timeout=1) payload = '<STX>
{
"TRAN_MODE":"1",
"TRAN_CODE":"1",
"AMOUNT":"450000"
}
<ETX>' 
ser.write(payload.encode()) response = ser.read(1024).decode() print("Raw Response:", response)

const SerialPort = require('serialport'); const port = new SerialPort('/dev/ttyUSB0', { baudRate: 9600 }); port.write('
<STX>
{
"TRAN_MODE":"1",
"TRAN_CODE":"1",
"AMOUNT":"450000"
}
<ETX>', (err) => {    if (err) return console.log('Error:', err.message);    
console.log('Payload sent.'); }); 
port.on('data', (data) => {    console.log('Raw Response:', data.toString()); });


#include <stdio.h> #include <fcntl.h> #include <termios.h> #include <unistd.h> int main() 
{    
int fd = open("/dev/ttyUSB0", O_RDWR | O_NOCTTY);    
struct termios tty;    
tcgetattr(fd, &tty);    
cfsetospeed(&tty, B9600);    
cfsetispeed(&tty, B9600);    
tty.c_cflag |= (CLOCAL | CREAD);    
tcsetattr(fd, TCSANOW, &tty);    
char payload[] = <STX>{\"TRAN_MODE\":\"1\",\"TRAN_CODE\":\"1\",\"AMOUNT\":\"450000\"}<ETX>";    
write(fd, payload, sizeof(payload));    
char buf[1024];    
int n = read(fd, buf, sizeof(buf));    
buf[n] = '\0';    
printf("Raw Response: %s\n", buf);    
close(fd);    return 0; 
}

Troubleshooting

Device not detected on Linux: Run ls /dev/ttyUSB* before and after connecting.

  • Ensure the user has permissions for the serial device (add to dialout group).

No USB Listening screen: Verify parameter download completed successfully.

  • Start USB manually from the terminal menu.

Payload not acknowledged: Ensure and are included exactly as required.

  • Check baud rate (default is 9600).

Conclusion

As we conclude our user guide, we are committed to creating a positive impact in delivering precision and perfection across all Valor platforms. This User guide for Semi Integration through USB is one of Valor’s recent innovations aimed at providing a secure and reliable electronic payment. We truly believe that this user guide serves as an indispensable source for your regular operations, and we are delighted to be a vital stakeholder in your business. We are immensely grateful for your encouragement and look forward to unwavering support.