Kushki ONE is currently in Beta for Mexico 🇲🇽. Do not deploy to production without coordinating with the Kushki integration team.
Two connection modes#
Kushki ONE supports two ways to connect your POS to the terminal:| Mode | How it works | Best for |
|---|
| Cloud | Your POS sends HTTP requests to Kushki's cloud, which pushes commands to the terminal | POS running in the cloud or on a different network from the terminal |
| Local Network | Your POS sends HTTP requests directly to the terminal's local IP over LAN or Wi-Fi | POS and terminal on the same local network |
Both modes expose the same operations — only the base URL and terminalSerial routing differ.
Two API sets#
| API | Description |
|---|
| Payment API | Charge, pre-authorize, capture, void, refund, post-tip, re-authorize, abort, and search transactions |
| Print API | Queue and monitor print jobs on the terminal's thermal printer — receipts, QR codes, barcodes, images |
Terminal models#
| Model | Description |
|---|
| Sunmi P3 | Handheld SmartPOS with thermal printer |
| Sunmi P2 SE | Compact countertop SmartPOS |
Cloud mode — Base URLs#
| Environment | URL |
|---|
| Production | https://cloudt.kushkipagos.com |
| UAT | https://uat-cloudt.kushkipagos.com |
Endpoint pattern: POST /terminal/v1/{terminalSerial}/sync/{operation}
Local Network mode — Base URL#
The terminal exposes an HTTP server on its local IP:http://{terminalIp}:{port}/terminal/v1/sync
| Variable | Default | Description |
|---|
terminalIp | 192.168.1.50 | Static IP or DHCP reservation of the terminal |
port | 6868 | Configured in the device management system (DMS) |
Authentication#
Kushki ONE uses HMAC-SHA256 request signing — not the Private-Merchant-Id header used in Online Payments.| Header | Required on | Description |
|---|
Authorization | Payment API (all requests with body) | Base64( HMAC-SHA256( rawBody, businessCode ) ) |
timestamp | Payment API (all requests) | Unix timestamp in milliseconds — must be within ±5 min of server time |
Print API (Cloud) and Print API (Local) do not require signed authentication headers.
Key integration notes#
Save transaction_reference from every charge or authorization response — required for void, refund, and capture calls.
Wait at least 1 minute after a transaction before calling void.
Void cutoff in Mexico: 22:00 local time on the same business day.
The terminal blocks during card interaction — your POS should not send another command until the current one completes.
To cancel an in-progress transaction, use the Abort operation.
Available API sections#
Payment API (Cloud)
Control payments via Kushki cloud infrastructure. No direct network access to the terminal required.
Payment API (Local Network)
Control payments by sending HTTP requests directly to the terminal's local IP.
Print API
Queue and monitor print jobs on the terminal's thermal printer — available in both Cloud and Local modes.
Payment API Reference
Full field reference for all payment operations — request bodies, responses, and field descriptions.
Got a suggestion on this documentation? Contact us.
