Kushki One

Beta — Early Access

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.

Kushki ONE Connect is a semi-integrated API that lets your POS system control a Kushki SmartPOS terminal (Sunmi P3 / P2 SE) — triggering card payments, managing pre-authorizations, adding tips, and printing receipts from your own application.

Your POS stays in control of the transaction flow. The terminal handles all card interaction and cryptographic processing.

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	HTTP on port `6868` or HTTPS on `6869` — the payload always travels encrypted; keep the terminal on a segmented network
Recommended HTTP timeout	90 s (relay latency)	15 s

INFO

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.

DANGER

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.

Async covers charge, authorization, capture, re-authorization, post-tip and void. Transaction search is sync-only in both modes; abort is sync-only in Cloud and available in both variants in Local.

Terminal models

Model	Description
Sunmi P3	Handheld SmartPOS with thermal printer
Sunmi P2 SE	Compact countertop SmartPOS

Base URLs

Cloud

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}

Local Network — the terminal exposes an HTTP server on its local IP:

http://{terminalIp}:6868/terminal/v1/{sync|async}/{operation}
https://{terminalIp}:6869/terminal/v1/{sync|async}/{operation}

Variable	Default	Description
`terminalIp`	`192.168.1.50`	Static IP or DHCP reservation of the terminal
`port`	`6868` HTTP · `6869` HTTPS	Both are open on the terminal. `terminalIp` and the ports are given to you by the integrations team during onboarding

Print operations keep their own paths in both modes — see Print Cloud and Print Local.

INFO

Before using Try it, pick the matching environment at the top right: Kushki ONE Cloud — UAT, Kushki ONE Cloud — Producción Kushki ONE Local (HTTP) or Kushki ONE Local — HTTPS. 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 one authentication mechanism, the same in Cloud, local network and localhost: hash + encryption. It is not the Private-Merchant-Id header used in Online Payments.

Header	Description
`Authorization`	`Basic` prefix followed by the SHA512 hash. The `Basic` prefix is required
`timestamp`	Unix timestamp in seconds (10 digits), within ±5 min of server time
Body	Always the encrypted envelope `{"data":"<iv_hex>:<cipher_hex>"}`. The payloads in this documentation are the plaintext you encrypt, not what travels on the wire

The Authorization and timestamp headers are required on every endpoint, Payment and Print alike. On operations with no payload, such as Abort, you sign the literal {}, not an empty string. Full details, including the data query-parameter variant used by GET operations on the local network, are on the Authentication page.

DANGER

Local network and localhost: always send the encrypted_http_communication: true header on every request, in UAT and in production. If you certify with the header set to false or without sending it, your requests are not signed or encrypted, and every call fails with AUTH-001 ("Invalid or expired credentials") when you move to production. Cloud integrations do not require this header.

DANGER

Never expose your Business-Code in client-side code or logs.

Amount format

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 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.

WARNING

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.

The tax field is named 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 and void.

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. The cutoff is midnight, local time: within the same calendar day /void cancels the transaction; from midnight onwards the same /void call enters the refund cycle and takes business days.

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.

Two connection modes#

Sync and async#

Terminal models#

Base URLs#

Authentication#

Amount format#

Key integration notes#

Where to go next#

Two connection modes

Sync and async

Terminal models

Base URLs

Authentication

Amount format

Key integration notes

Where to go next