API Reference

Semi Integration Support via USB

Introduction

This guide provides instructions for establishing USB-based communication between supported Valor POS terminals (excluding VL500) and third-party software applications.
It outlines the steps required to enable secure, real-time transaction exchange, allowing external systems to seamlessly integrate with Valor devices for 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 for Valor terminals running application version 3.0.46 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.46 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.6 (for complete list of API payloads).

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.
  • 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.

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.)

Python Example (Phyton)

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)

Node.js Example (Javascript)

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()); });

C Example (C Language)

#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

If you encounter issues during configuration or communication, refer to the scenarios below:

Device Not Detected on Linux PC
  • Run the following command before and after connecting the device:
ls /dev/ttyUSB*
  • Ensure the user has permission to access the serial device.
  • Add the user to the dialout group if required.
Device Not Detected on Windows PC
  • Open Device Manager.
  • Navigate to Ports (COM & LPT).
  • Look for a COM port labeled Android Diag (or similar).
“USB Listening” Screen Not Displayed
  • Verify that the parameter download has completed successfully.
  • Restart the terminal.
  • Manually initiate USB mode from the terminal menu if required.
Payload Not Acknowledged
  • Ensure and control characters are included exactly as specified.
  • Verify the baud rate configuration (default: 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.