How to choose a connection protocol for linking a bank terminal to Torgsoft: BPOS, PosApi, SSI, JSON, and OschadPAY

When a bank terminal is connected to Torgsoft, the cashier does not need to enter the purchase amount manually on the terminal: in Torgsoft, card payment is selected, the software sends the amount to the terminal and receives the transaction result. This mode is called bank terminal integration with the checkout or cash register integration. 

Business owners usually ask which protocol to order from the bank, whether a particular terminal model is suitable, what is better for a local checkout or a remote server, whether a static IP address is required, and how to work with several Sole Proprietorships through one terminal. Support requests show that the main issue is not finding the «best» protocol, but correctly matching the same connection method between the bank, the terminal, and Torgsoft.

What is a bank terminal protocol?

A protocol is the method by which Torgsoft and the bank terminal exchange data.

For example, Torgsoft sends the terminal:

• the amount to be paid;

• a payment or refund command;

• merchant data, if required.

The terminal returns the transaction result and the available payment details.

Torgsoft supports various integration methods, including BPOS, PosApi, SSIAxECR, SSI_JSON, WebSocket/JSON, JSON (COM/TCP), OschadPAY, BankCore, QRPayMono, and other current options. For some protocols, the bank must provide drivers or libraries.

 It is important not to confuse three things:

• protocol — how Torgsoft and the terminal exchange commands;

• connection — how they are connected physically or over a network: USB/COM, Ethernet, Wi-Fi;

• merchant — the bank's merchant identifier linked to a specific Sole Proprietorship and account.

This means that a terminal can operate via Wi-Fi while using BPOS or JSON. Wi-Fi is not an acquiring protocol.

The main rule for choosing a protocol

You should not choose BPOS, PosApi, or JSON on your own based only on the bank name or terminal model.

First, ask the bank:

1. Whether this terminal can operate in cash register integration mode.

2. Which specific protocol the bank can configure on this terminal.

3. How the terminal will be connected: USB/COM, Ethernet, or Wi-Fi.

4. Which drivers and libraries the bank provides for integration.

5. Whether the required merchants are configured for payments and refunds.

After that, the corresponding protocol is selected in Torgsoft.

This is not a formality. Torgsoft support encountered a case involving a Newland N950 from PrivatBank: the terminal itself was working properly, but it could not be connected to Torgsoft because the bank had not configured the device to operate in cash register integration mode. The client was advised to contact the bank and configure JSON via Wi-Fi.

Therefore, having a compatible terminal model alone is not enough. The required operating mode must also be configured correctly on the terminal.

In brief: how the main options differ

There is no point in comparing them on the basis that one is «better» or «worse». You need the option that is simultaneously supported by the bank, the specific equipment, and Torgsoft.

BPOS and BPOS1

For BPOS, the bank provides the necessary drivers and the ECRCommX.dll library. Torgsoft supports this protocol for integration with bank terminals.

BPOS has an important feature: in practice, there are two modes.

This matters when the payment has been completed on the terminal, but due to a communication failure, the software has not received or confirmed the result. The instructions for connecting PrivatBank POS terminals describe this exact difference between BPOS and BPOS1.

The business owner does not need to «switch BPOS to BPOS1» independently. If there are discrepancies between the result on the terminal and the checkout, check with the bank which mode is configured.

In Torgsoft technical support requests, BPOS is also used for network connections of Ingenico terminals via Ethernet: the port was configured, the terminal's IP address was reserved, and the connection was checked.

When to choose BPOS

If the bank confirms that a specific terminal uses BPOS for cash register integration and provides the required connection components, this protocol can be used in Torgsoft.

If the checkout operates remotely via RDP, inform the bank and Torgsoft technical support about this immediately: in this scenario, not only the protocol but also the network connection and correct transaction confirmation become important.

PosApi

Torgsoft supports PosApi as a separate protocol. It requires a terminal driver and the Posapi.dll library, which are provided for the corresponding banking equipment. The current Torgsoft documentation includes, in particular, a separate guide for the Raiffeisen Bank Verifone VX520.

For a business owner, the logic is simple: the bank says that the terminal works with the checkout via PosApi → the bank provides the required software → PosApi is configured in Torgsoft.

There is no need to choose PosApi simply because the terminal is made by a particular manufacturer. The current Torgsoft documentation specifically states that the bank terminal type field is auxiliary, while the selected protocol determines the operating algorithm.

SSI: SSIAxECR and SSI_JSON

Torgsoft has two separate options:

• SSIAxECR;

• SSI_JSON.

They should not be treated as a single interchangeable setting.

For example, the Torgsoft documentation contains a separate SSIAxECR guide for the Verifone X990, while SSI_JSON is configured as a different protocol.

Therefore, when receiving a terminal, it is not enough to ask the bank: «Do we have SSI?». You need to clarify the exact name of the protocol configured on the device.

What to ask the bank

It is enough to say: "The terminal needs to be integrated with the Torgsoft checkout software. Please specify which SSI protocol is configured: SSIAxECR or SSI_JSON, and provide the connection parameters".

This is much more useful than trying to select the settings in the software independently.

JSON: one name, several options

JSON most often causes confusion because JSON is not a single terminal setting.

Torgsoft includes, in particular:

• WebSocket/JSON;

• JSON (COM/TCP).

For WebSocket/JSON, the documentation provides separate components for network and USB/COM connections. JSON (COM/TCP) uses a different data exchange method.

Therefore, the bank's answer that «the terminal works via JSON» is not sufficient. You need to clarify:

• which specific JSON option is used;

• whether the connection is USB/COM or network-based;

• for a network connection — the IP address and port;

• whether the bank has already switched the terminal to cash register integration mode.

Support experience confirms this. With the PrivatBank Newland N950, both Wi-Fi connections within a local network and other integration options have been encountered. Technical support checked the IP address, router settings, and connection to the terminal.

Therefore, the formula «Newland = JSON = any settings will work» is incorrect. You need to know exactly how the bank has configured this particular device.

OschadPAY: a separate smartphone scenario

OschadPAY differs from BPOS, PosApi, and other options designed for conventional POS terminals.

Torgsoft integration with OschadPAY was added for accepting contactless payments via a smartphone. A phone with the corresponding functionality is used to accept card payments without a separate stationary POS terminal.

Therefore, OschadPAY is worth considering when this specific scenario is required, for example, for a mobile checkout or a retail environment where installing a separate bank terminal is inconvenient.

If a store has received a conventional POS terminal from Oschadbank, OschadPAY should not be selected automatically. First, ask the bank which cash register integration method is used specifically for the equipment provided.

USB, Ethernet, or Wi-Fi

The protocol and connection method need to be selected together.

If Torgsoft runs on the computer at the checkout

USB/COM may be convenient if this is the connection method provided by the bank for the terminal.

In this scenario, there is no separate network route between the software and the terminal.

If the terminal operates via Ethernet or Wi-Fi

The terminal has its own IP address on the network. It is important that it does not change unexpectedly.

In actual support requests, technical support:

• checks the terminal's IP address;

• reserves the address in the router;

• checks the required port;

• checks whether the device is reachable;

• then performs a test payment.

If the router assigns a different IP address to the terminal, Torgsoft may simply stop detecting it, even though the POS terminal itself continues to operate as a standalone bank terminal.

What changes when using a remote server or RDP?

Here it is important to understand where the two devices are located:

• the POS terminal is physically located in the store;

• Torgsoft may be running on a server at another location.

Therefore, the server must be able to send a command to the terminal in the store and receive a response.

For this reason, when working remotely, you need to check:

• which protocol is being used;

• whether it supports the selected network scenario;

• the terminal's IP address;

• the required port;

• router and firewall settings;

• whether the terminal is accessible from the environment where Torgsoft is running.

Technical support records include cases where there was no connection to the POS terminal specifically because of network parameters or an IP address change. There was also a case where a static IP address was required for the store to operate.

However, the rule «for any RDP setup, you must purchase an external static IP address and configure Port Forwarding» is incorrect. It depends on how the specific network is configured. The connection scheme should be determined first.

If several Sole Proprietorships use one terminal

The protocol alone does not resolve this issue.

For each business owner, the following must be linked correctly: Sole Proprietorship → current account → merchant → bank terminal.

Torgsoft technical support regularly handles requests involving:

• adding a new Sole Proprietorship;

• checking whether it is available on the terminal;

• adding the corresponding merchant in Torgsoft;

• configuring links to accounts;

• checking payments and refunds.

If the bank has not added the required merchant to the terminal, configuring it only in Torgsoft is not enough.

This should be checked before the checkout starts operating, not after the first payment has been credited to another Sole Proprietorship's account.

Why can the terminal be connected while payments still work incorrectly?

The fact that Torgsoft detects the terminal only means that a connection has been established.

After connection, other issues may remain:

• the wrong merchant is selected;

• the terminal has been configured by the bank for a different mode;

• the software and the POS terminal interpreted the transaction result differently;

• payments work, but refunds have not been configured;

• after the router was changed, the terminal received a different IP address.

Therefore, after configuration, you need to check not only the connection but the entire workflow.

How to check the terminal correctly after connection

After configuration, it is worth performing a short test.

1. Check the connection to the terminal.

2. Make a small test payment.

3. Check that the amount was transferred automatically from Torgsoft.

4. Check the Merchant ID and the required Sole Proprietorship.

5. Make sure the sale was completed correctly in Torgsoft.

6. Check the fiscal receipt if an ECR/pECR is used.

7. Perform a test refund.

8. Make sure the funds and documents are reflected correctly.

The Torgsoft knowledge base recommends a test payment, merchant verification, and a test refund after configuring a bank terminal.

This makes it possible to immediately identify a situation where a sale works but a refund does not.

What to tell the bank before receiving the terminal

A business owner does not need to know all the technical differences between BPOS, SSI, and JSON.

It is enough to give the bank a specific task: "I need a bank terminal for integration with Torgsoft software in cash register integration mode. Please tell me which integration protocol is available for this model and bank, how the terminal connects to the checkout, and which drivers, libraries, and parameters are required for the connection".

If Torgsoft operates through a remote server, mention this immediately.

If several Sole Proprietorships will use one terminal, this should also be agreed with the bank before configuration.

How to choose a protocol: a practical scheme

◆ If you already have a terminal, first ask the bank which cash register integration protocol is configured on it. Then compare it with the protocols supported by Torgsoft.

◆ If you are only ordering a terminal, tell the bank that you need integration with Torgsoft and ask which protocol and connection method are available.

◆ If Torgsoft runs on a remote server, add a check of network access to the POS terminal when choosing the protocol.

◆ If several Sole Proprietorships are used, separately agree with the bank on the merchants for each business.

◆ If you need smartphone payments without a separate POS terminal, OschadPAY can be considered as a separate scenario.

The key point

There is no need to choose BPOS, PosApi, SSI, or JSON based on which one is «more modern». The correct protocol for a store is the one that the bank has configured on the specific terminal, that Torgsoft supports, and that the selected connection scheme allows to reliably transmit payments and receive transaction results.

Before launching the checkout, it is enough to check five things: protocol → connection method → IP/port if required → merchant → test payment and refund.

These are the points that most often determine whether the integration will work correctly in day-to-day retail operations.