Kushki ONE is currently in Beta for México 🇲🇽. Endpoints, parameters and response structures may change without prior notice. Do not deploy to production without coordinating with the Kushki integration team.
Two connection modes#
| Mode | How it works | Best for |
|---|
| Cloud | Your POS calls Kushki's cloud, which pushes the command to the terminal | POS running in the cloud, or on a different network from the terminal |
| Local Network | Your POS calls the terminal's local IP directly over LAN or Wi-Fi | POS and terminal on the same local network |
The two modes cover the same operations, but they are not interchangeable. Beyond the base URL, these differ: | Cloud | Local Network |
|---|
| Terminal addressing | terminalSerial in the path | The terminal's IP and port |
| Abort | POST /sync/abort, sync only | GET /sync/abort and GET /async/abort |
| Transaction search | One unified endpoint | Two: acquirer-side and on-device |
| Print status | POST /sync/print_job, ID in the body | GET /print_job?print_job_id= |
| Print webhook | — | POST to your webhookUrl, implemented by your POS |
| Transport | HTTPS | Plain HTTP, unencrypted — keep the terminal on a segmented network |
| Recommended HTTP timeout | 90 s (relay latency) | 15 s |
| Endpoints | 17 | 20 |
Sync and async#
Every payment operation exists twice, under two path prefixes, in both modes:| Variant | Prefix | HTTP response | Where the outcome arrives |
|---|
| Sync | /sync/ | Blocks until the acquirer answers, then returns the full result | In the HTTP response |
| Async | /async/ | Returns immediately with a TERMINAL_ACKNOWLEDGED event | On the webhook you register |
Async exists because card-present flows wait on a human and routinely exceed the ~15 second timeout budget of most POS architectures.The async response is an acknowledgement, not a result. To learn whether the transaction was approved you must consume the events webhook — supply events_webhook_url in the request body. The field is accepted on /async/ endpoints only.
Terminal models#
| Model | Description |
|---|
| Sunmi P3 | Handheld SmartPOS with thermal printer |
| Sunmi P2 SE | Compact countertop SmartPOS |
Base URLs#
| Environment | URL | Selector |
|---|
| Production | https://cloudt.kushkipagos.com | Kushki ONE Cloud — Producción |
| UAT | https://uat-cloudt.kushkipagos.com | Kushki ONE Cloud — UAT |
POST /terminal/v1/{terminalSerial}/{sync|async}/{operation}
http://{terminalIp}:{port}/terminal/v1/{sync|async}/{operation}
| 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) |
Before using Try it, pick the matching environment at the top right: Kushki ONE Cloud — UAT, Kushki ONE Cloud — Producción or Kushki ONE Local. The default UAT Testing Env points at api-uat.kushkipagos.com, the Online Payments host, where Kushki ONE does not answer.
Authentication#
Kushki ONE uses HMAC-SHA256 request signing — not the Private-Merchant-Id header used in Online Payments.| Header | Description |
|---|
Authorization | Base64( HMAC-SHA256( rawRequestBody, businessCode ) ) |
timestamp | Unix timestamp in milliseconds (13 digits), within ±5 min of server time |
Both headers are required on every endpoint, Payment and Print alike. On bodyless requests such as Abort, the signature is computed over an empty string.Never expose your Business-Code in client-side code or logs.
Amounts are integers in cents and the currency is always MXN, which has two decimal places. Send 1200 to charge 12.00 MXN — never drop the cents, never send separators. There is no currency field; the terminal's DMS configuration decides it.Requests take integers, but event and webhook payloads echo amounts back as decimals (12000.0). Do not re-send an echoed value as an amount.If your POS also serves a zero-decimal market such as Colombia, resolve the decimal handling per terminal — do not share one code path.
Key integration notes#
Save rawResponse.transaction_reference from every charge or authorization — required for capture, re-authorization, void and refund.
client_transaction_id is your idempotency key. Retry with the same UUID; the terminal deduplicates.
Wait at least 1 minute after a transaction before calling void. Cutoff in Mexico is around 22:59 local on the same business day; after that the transaction has settled and must be reversed with refund.
The terminal handles one transaction at a time. Do not send another command until the current one completes.
APPROVAL_REQUESTED is the point of no return — once the transaction reaches the acquirer, abort returns 409.
A capture is capped at 110% of the authorization plus all non-canceled re-authorizations, and there is exactly one capture per authorization cycle.
Where to go next#
Cloud Services
Control the terminal through Kushki's cloud. No direct network access required.
Local Network Services
Call the terminal's local IP directly. Lowest latency, no cloud dependency.
Webhooks
The seven transaction states, the event envelope, and the retry policy.
Transaction Examples
Copy-ready request bodies for every operation, with amounts worked out in MXN.
Error Catalog
Every error code grouped by category, with the recommended action.
Release notes
Feature releases, improvements and bug fixes of Kushki ONE.
Got a suggestion on this documentation? Contact us.
