First Steps

September 10, 2026

Know Kushki ONE, our regional solution for Card Present payments.

What is Kushki ONE?

Kushki ONE is Kushki’s end-to-end card-present payments solution. It lets merchants accept physical payments through SmartPOS terminals, bringing the whole operation into a single ecosystem.

Accept payments directly from the payment app installed on the terminal, or connect your point-of-sale software through our API. Run it from a register, tablet, computer or any other networked device, or from an app installed on the terminal itself.

Markets and currencies

How to use this guide

This documentation splits into two paths depending on your role.

Path 1: For Merchant Operators and Administrators

Supported Hardware

Kushki ONE’s architecture is hardware-agnostic and all of its components are interoperable. To guarantee maximum performance and stability, however, the solution is certified only for these SmartPOS devices.

Sunmi P3

• Built-in printer: high-speed thermal, 70 mm/s.
• Battery: removable lithium, 7.7 V and 2,630 mAh. Up to 13 days on standby.
• Design: ultra-thin at 17 mm with anti-fingerprint coating, built for high-traffic environments.

Sunmi P2 SE

• Mobility: compact and lightweight, ideal for pay-at-table, retail or delivery.
• Code reader: professional scan engine for barcodes and QR codes, even when damaged.
• Durability: resistant to dust, splashes and drops. Battery optimized for long shifts.

Kushki ONE Payment App

This is the payment app installed directly on the physical terminal. Its interface lets the operator run and manage the entire payment lifecycle without an external point of sale.

Operations Catalog

Terminal Operating Modes

Standalone mode

• The terminal runs on its own, with no integration to external systems.
• The operator uses the touchscreen as a calculator. The whole cycle happens on the device.
• Ideal for merchants without an external point-of-sale system.

Semi-Integrated mode

• Required to connect your point of sale to the terminal through Kushki ONE Connect.
• The interface locks into a “Waiting for call” state and only reacts to commands sent by your POS software.
• Ideal for integrations with your own point of sale.

Path 2: For Developers and Integrators (Kushki ONE Connect)

What is Kushki ONE Connect?

Kushki ONE Connect is our API integration layer. It lets your POS software interact directly with the physical terminal while it runs in Semi-Integrated mode. Your system sends the financial commands to the payment app, which removes manual entry and human error.

The premise is simple: it is the same API regardless of the channel you use. The only thing that changes between topologies is the communication path, not the structure of the endpoints or the payloads.

Integration Topologies (Communication Paths)

1. Cloud integration

Your POS sends the request to Kushki’s servers, which identify the target terminal and route the order over the internet.

• Advantage: your POS and the terminal do not need to share a local network.
• Consideration: requires a stable internet connection at both ends.

Every endpoint carries the terminal serial number in the path:

https://{host}/terminal/v1/{terminalSerial}/sync/{operation}

2. Local Network integration

Your POS sends an HTTP request straight to the terminal’s local IP, with no detour through external servers. That cuts latency noticeably.

• Advantage: lower latency, because POS-to-terminal communication does not depend on the internet.
• Consideration: the terminal needs a static IP or a DHCP reservation. If the IP changes, your POS loses communication.

How to find your terminal’s IP

1. Open Settings and then Wi-Fi.
2. Tap the name of the connected network.
3. Expand Advanced options.
4. Scroll down to the IP address field.

3. Same-device integration (Localhost)

This applies when you have your own POS app installed inside the SmartPOS terminal. Your app and the Kushki ONE Payment App live on the same hardware and talk to each other over localhost.

• Main advantage: replaces traditional app-to-app integration flows with standard HTTP calls.
• No internal network: communication between the two apps needs neither Wi-Fi nor Ethernet.

Communication Security

Every call to Kushki ONE Connect is authenticated with a signature you compute from your Business-Code.

The mechanism does not change between topologies: your authentication logic is the same on Cloud, Local Network and Localhost. There is one mechanism — hash + encryption:

Network and Infrastructure Requirements

1. Local network setup

This applies only if you use the Local Network topology.

• Static IP or DHCP reservation: configure the router to always assign the same IP to the terminal, bound to its MAC address.
• Communication ports: the internal firewall must allow bidirectional traffic on the terminal’s TCP ports — 6868 for HTTP and 6869 for HTTPS. A network that only opens 6868 blocks HTTPS access to the terminal.
• Wi-Fi security: certified terminals support WPA2-PSK and WPA3.

2. Allowed domains

The terminal always needs internet access to process transactions and receive updates. If your corporate network blocks outbound traffic, your IT team must allow these hosts on port 443. Open only the column for your environment — uat-cloudt is a test host and does not belong on a production network:

All three are real egress from the terminal. The only row you also have to open from the POS network is the Cloud relay, and only if you integrate over that topology.

Full Transaction Flow

1. Request generation: your POS system builds the request and sends the amount to charge over the API.
2. Decision and routing: Kushki ONE Connect receives the request and routes it to the physical device according to the merchant’s configuration, over Cloud or Local Network.
3. Reception and data capture: the terminal receives the request, shows the amount on screen and reads the customer’s card.
4. Processing: the terminal sends the data to Kushki, which processes the financial transaction.

Verify your connection

Before your first charge, check that your POS can reach the terminal. This endpoint moves no money and is the fastest way to validate network, port and credentials at once.

// Local Network
const res = await fetch("http://192.168.1.50:6868/terminal/v1/sync/local/test", {
  headers: buildHeaders({}),
});

console.log(res.status, await res.json());
// 200  { success: true, data: {} }

import requests

# Local Network
res = requests.get("http://192.168.1.50:6868/terminal/v1/sync/local/test",
                   headers=build_headers({}))

print(res.status_code, res.json())
# 200  {'success': True, 'data': {}}

The same check exists on Cloud, where the method changes — it is a POST addressed to the terminal by serial number:

POST /terminal/v1/{terminalSerial}/sync/local/test

There is a second diagnostic endpoint worth knowing, available in both topologies:

GET  /terminal/v1/sync/config/terminal_info                     ← local network
POST /terminal/v1/{terminalSerial}/sync/config/terminal_info    ← Cloud

It returns {model, room, serialNumber}. The room field is the terminal’s app version — the only way to know which build you are testing against, which matters while the product is in Beta.

If you get a TER-002 error, the terminal is not responding: check network connectivity and that the port is open. If you get an authentication error, check your signature.

Next steps