Kushki ONE is currently in Beta for Perú 🇵🇪. 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: transaction_search_online and transaction_search_local |
| 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 |
In Peru the Apidog folders carry the mode in their name — Payment Cloud and Print Cloud under Cloud Services, Payment Local and Print Local under Local Services. It is the same operation set as the other markets, only the folder names differ.
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 the currency's smallest unit. The terminal is provisioned in PEN or USD, and both have two decimal places — so the last two digits are always the fractional part. Send 1200 to charge S/ 12.00, and never drop the trailing zeros. 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.Confirm which of the two currencies your terminal is provisioned for before you reconcile — the payload looks identical either way. If your POS also serves a zero-decimal market such as Chile or Colombia, resolve the decimal handling per terminal; do not share one code path.
iva in the payload even though the tax in Peru is the IGV (18%). It is the field name, not a different tax.
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 Peru is around 23:59 local on the same business day; after that the transaction has settled and must be reversed with refund.
Peru does not observe daylight saving time — America/Lima stays on UTC-5 all year. Still resolve it with a timezone library when you build the millisecond timestamps for transaction search.
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 PEN.
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.
