Know Kushki ONE, our regional solution for Card Present payments.
🚧 Early Release — Beta
This product is in early access. Parameters, response structures and behaviors may change without prior notice. Do not use this version in production without coordinating with the Kushki integrations team first.
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.
The number of decimals changes how you send the amount
Amounts are sent as integers in the currency's smallest unit, and the result depends on the country. Read Amount format in Kushki ONE before you build your first request.
This documentation splits into two paths depending on your role.
Path 1: operators and administrators
For those who run the point of sale or manage the business: certified hardware, the Payment App, the operations catalog and the Standalone and Semi-Integrated modes.
Path 2: developers and integrators
For those who connect POS software to the terminal: Kushki ONE Connect, integration topologies, security, network requirements and the full transaction flow.
Path 1: For Merchant Operators and Administrators#
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.
Model
Display and design
Processor and memory
Operating system
Sunmi P3 (standard)
6.75" HD+ bezel-less (350 nits). Ultra-thin at 17 mm with anti-fingerprint coating
Quad-Core A53 at 2.0 GHz, 2 GB RAM, 32 GB ROM
Sunmi OS (Android 11 Go)
Sunmi P2 SE
Compact display. Lightweight, resistant to dust, splashes and drops. QR and barcode scan engine
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.
Single-step charge. Supports tip, merchant-funded installments, issuer-funded installments and cashback
Authorization
✅
Reserves the funds on the card for a later charge
Capture
✅
Charges an amount that was previously authorized
Re-authorization
✅
Changes the authorized amount or extends the window to run the capture
Return
✅
Gives the money back from a sale. Internally it runs a void or a refund depending on when it executes
Post-tip
✅
Adds a tip amount after a transaction has been authorized
Split the bill
❌
Splits one amount into several sequential payments. Standalone only — there is no endpoint for it
Splitting the bill is not Split Payment
These are chained payments that make it easier to divide a single check, for example at a restaurant. Do not confuse them with e-commerce Split Payment operations, which distribute one payment across several merchants.
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.
Cloud POS, multi-site merchants, POS and terminal on different networks
Supermarkets, retail and restaurants on the same network
Your own POS app installed on the terminal
Key requirement
Stable internet at both the register and the terminal
Static IP or DHCP reservation on the terminal
No internal network needed between the apps
Internet is always required
Localhost communication needs no network between the apps, but the device always needs internet access to process the financial transaction with Kushki.
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.
Every call to Kushki ONE Connect is authenticated with a signature you compute from your Business-Code.
Business-Code is not private_credential_id
The signing key is your Business-Code. The private_credential_id is a terminal configuration field and is never used to sign requests.
The signing and encryption logic does not change between topologies: it is the same on Cloud, Local Network and Localhost. There is one mechanism — hash + encryption:
Element
Value
Authorization
Basic followed by the SHA-512 hash
timestamp
Unix timestamp in seconds, within ±5 minutes of server time
Body
The encrypted envelope {"data": "<iv_hex>:<ciphertext_hex>"}
In Local Network and Localhost, send the encrypted_http_communication header as true
If you integrate over Local Network or Localhost, send the header encrypted_http_communication: true on every request, in UAT and in production. Without it, your requests are not signed or encrypted, and when you move to production they fail with AUTH-001 ("Invalid or expired credentials"). Cloud integrations do not require this header.
Write it once
The signing and encryption logic in this section is the same across all three topologies. The full flow — key derivation, the seven steps and the diagnostic tree — is on Authentication and request encryption.
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.
Networks to avoid
Do not connect terminals to open public networks or to networks with captive portals, which require a username and password in a browser to grant access.
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:
Purpose
UAT
Production
Who needs it
Cloud relay
uat-cloudt.kushkipagos.com
cloudt.kushkipagos.com
The terminal and the POS network
Payment processing
api-uat.kushkipagos.com
api.kushkipagos.com
The terminal only
Terminal management
uat-tms.kushkipagos.com
tms.kushkipagos.com
The terminal only
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.
Port 6868 and port 443 are not the same thing
Ports 6868 and 6869 are the terminal's local listening ports and apply only to communication between your POS and the terminal inside the same network. Traffic to Kushki's servers always uses port 443. If your network policy requires an exhaustive list that includes the manufacturer's telemetry services, request it from the integrations team.
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.
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.
JavaScript
Python
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.
