First Steps

March 31, 2026

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

Supported brands

What is Kushki ONE?

Kushki ONE is Kushki’s comprehensive card-present payment solution. It is designed for merchants to receive physical payments through SmartPOS terminals, unifying the entire operation into a single ecosystem.

It allows you to receive payments using the payment application installed on the terminal directly, or by connecting your point of sale (POS) software through our API. It can operate from a cash register, tablet, computer, or another device with a network connection, or from an app installed on the terminal itself.

How to use this guide?

This documentation is divided into two main paths according to your role:

• Supported hardware (Sunmi P3, P2 SE)
• Kushki ONE Payment App
• Operations: Sale, Void/Refund, Post Tip, Split Bill
• Modes: Standalone and Semi-Integrated

• What is Kushki ONE Connect?
• Topologies: Cloud, Local Network, and Localhost
• Security and authentication (Hash / Private-Credential-Id)
• Network and infrastructure requirements
• Complete transaction flow

Path 1: For Operators and Merchant Administrators

Supported Hardware

Kushki ONE’s architecture is hardware-agnostic; all its components are interoperable. However, to ensure maximum performance and stability, the solution is certified only for the following SmartPOS devices:

Sunmi P3 — Additional features

• Integrated printer: High-speed thermal printer (70 mm/s).
• Battery: Removable lithium (7.7 V / 2630 mAh). Up to 13 days on standby.
• Design: Ultra-slim (17 mm) with anti-fingerprint coating, designed for high-traffic environments.

Sunmi P2 SE — Additional features

• Mobility: Compact and lightweight design, ideal for pay-at-the-table, retail, or delivery.
• Code reader: Professional scanning engine for barcodes and QR codes, even damaged ones.
• Durability: Resistant to dust, splashes, and drops. Battery optimized for long shifts.

Kushki ONE Payment App

It is the payment application installed directly on the physical terminal. Its intuitive interface allows operators to execute and manage the full lifecycle of a payment without the need for an external POS (Standalone mode).

Operations Catalog

Terminal Operating Modes

There are two modes:

Standalone Mode (Independent)

• The terminal works 100% autonomously, without integration with external systems.
• The operator uses the touch screen as a calculator. The entire cycle (charging, returns) is performed on the device.
• Ideal for: merchants without an external POS system.

Semi-Integrated Mode

• Required to connect your POS with the terminal via Kushki ONE Connect (API).
• The interface locks in a “Waiting for call” state. It only reacts to commands sent from your checkout software.
• Ideal for: integration with your own POS (Path 2).

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

What is Kushki ONE Connect?

Kushki ONE Connect is our API integration layer that allows your checkout software to interact directly with the physical terminal when it is in Semi-Integrated mode. Your system sends financial commands (Sale, Void/Refund, etc.) to the payment application, eliminating manual typing and human errors.

The central premise is simple: it is the same API regardless of the channel you use to connect your POS with the terminal. The only thing that varies between the three topologies is the communication path, not the structure of the endpoints or the payloads.

Integration Topologies (Communication Paths)

Kushki ONE Connect offers three ways to send requests to the terminal. The following table summarizes the differences before going into detail:

*Internal communication (localhost) does not require a network between apps, but the device does need internet access to process the financial transaction.

1. Cloud Integration (Internet)

Your POS sends the request to Kushki’s servers. These identify which terminal the command is addressed to and forward it over the internet.

• Ideal for: Cloud POS systems, multi-location merchants, or environments where the POS and terminal are on separate networks.
• Advantage: Does not require the POS and terminal to share the same local network.
• Consideration: Requires a stable internet connection on both the POS and the terminal.

Connection hosts:

All endpoints include the terminal serial number in the path:

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

2. Integration via Local Network (Wi-Fi / LAN)

Your POS sends an HTTP request directly to the terminal’s local IP, without triangulating with external servers. This drastically reduces latency.

• Ideal use case: Supermarkets, retail, or restaurants where POS and terminals operate under the same Wi-Fi or closed LAN network.
• Advantage: Lower latency by not depending on the internet for internal communication between POS and terminal.
• Key consideration: The terminal should ideally have a static IP or DHCP reservation. If the IP changes, the POS loses communication, so it will be necessary to take this into account in the case of changing IPs.

How to find your terminal’s IP?

If you use Path 2 (Local Network), follow these steps on the device:

• Go to Settings > Wi-Fi.
• Tap the name of the connected network.
• Expand Advanced options.
• Scroll down until you find the IP Address field.

3. Integration on the Same Device (Localhost / App-to-App)

Applies when you have your own POS app installed within the same SmartPOS terminal. Your app and the Kushki ONE Payment App coexist on the same hardware and communicate by pointing to localhost.

• Main advantage: Replaces traditional complex App-to-App integration flows. Uses standard HTTP calls instantly.
• No internal network required: Communication between the two apps does not need Wi-Fi or Ethernet.
• Internet is still necessary: The device always requires internet access to process the transaction with Kushki.

Complete Transaction Flow

The following flow describes the interaction between all components from the initiation of a payment intent until receiving the response:

1. Request generation: The merchant’s checkout system (POS) generates the request by sending the amount to be charged via API to the payment ecosystem.
2. Decision and Routing: Kushki ONE Connect receives the request and makes a routing decision based on the configuration chosen by the merchant; in this way, it routes the request to the physical device, either through the Cloud or via the Local Network.
3. Reception at the terminal and data capture: Kushki ONE Connect sends the charge request to the SmartPOS Terminal. The terminal receives the request, displays the amount to be paid on the screen, and reads the customer’s card.
4. Transaction processing: Once the data is read, the terminal sends the information to Kushki, which is ultimately responsible for processing the financial transaction.

Communication Security

Regardless of the chosen topology, all communications to Kushki ONE Connect must be authenticated by sending a security Hash generated from your Private-Credential-Id.

Network and Infrastructure Requirements

To ensure that communication between your POS and the terminal is fast, stable, and secure:

1. Local Network Configuration (LAN / Wi-Fi)

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 (associated with its MAC). If the IP changes dynamically, the POS will lose communication.
• Communication port: The internal firewall must allow bidirectional traffic on the terminal’s TCP listening port 6868.
• Wi-Fi Security: Certified terminals support networks with WPA2-PSK / WPA3 protocols.

2. Allowed Domains (Allowlisting)

The terminal always requires internet access to process transactions and receive updates. If your corporate network blocks outbound traffic, your IT team must allow the following domains on port 443 (HTTPS):

• Payment processing: api.kushkipagos.com
• Terminal management (DMS): tms.kushkipagos.com
• Sunmi hardware and telemetry services: [SUNMI_DOMAIN — if applicable]

Next Steps

Once the base configuration is complete, you are ready to integrate the terminal interaction services: