Kushki One

Kushki ONE is a semi-integrated payment solution for Sunmi SmartPOS terminals (P3, P2 SE). Your POS system sends commands to the terminal via HTTP — either through Kushki's cloud infrastructure or directly over your local network — and the terminal handles card reading, PIN entry, EMV processing, and thermal printing natively.

Beta

Kushki ONE is currently in Beta phase. Contact your account manager to request access before deploying to production.

Connectivity modes

Kushki ONE supports two integration modes. Choose based on your infrastructure:

	Cloud Mode	Local Network Mode
Your server connects to	`cloudt.kushkipagos.com`	Terminal IP directly
Terminal identified by	Serial number in URL path	IP address + port 6868
Works without internet	❌	✅ (local connection)
Print auth required	✅ HMAC-SHA256	❌
Payment auth key	`Private-Credential-Id`	`Business-Code`

Payment operations

The following operations are available in both Cloud and Local modes.

Charge

Single or deferred card charge in one step. Supports tip and cashback (configured in DMS).

Authorization

Place a hold on the card without capturing funds. Use before Capture or Re-authorization.

Capture

Capture a previously authorized amount. Maximum = 110% of total authorized (including re-authorizations). One capture per authorization cycle.

Re-authorization

Extend or increase an existing authorization before capture. Debit cards: 7-day limit. Credit cards: 28-day limit.

Void

Cancel an authorization or same-day charge before settlement. Peru cutoff: 20:59 local time.

Refund

Refund a settled transaction — full or partial. Requires transaction_reference from the original response.

Abort

Cancel a transaction currently in progress on the terminal (e.g., customer walks away mid-flow).

POS Tip

Display a tip entry screen on the terminal and retrieve the amount the customer selected.

Transaction search

Operation	Available in	Source	Works offline
Transaction Search	Cloud + Local	Kushki acquirer backend	❌
Transaction Search (Local)	Local only	Terminal storage	✅

The local search endpoint queries transactions stored on the terminal itself — useful as an offline fallback or for same-day recovery.

Print operations

Both Cloud and Local modes support thermal printer control. Print jobs are asynchronous — the terminal returns 202 Accepted immediately and delivers the final status via webhook or polling.

Create Print Job

Send an ordered commands array describing the receipt layout. The terminal queues and executes it asynchronously.

Get Print Job Status

Poll the current status of a queued job using printJobId. Returns PENDING, COMPLETED, or FAILED.

Print Job Webhook

The terminal POSTs to your webhookUrl when the job finishes. Implement this in your POS to avoid polling. (Local mode only)

Print command types

Every print job is an ordered commands array. The type field on each object determines how it renders:

`type`	Description
`text`	Text line — configurable size, alignment, bold, italic, underline
`columns`	Multi-column row with proportional widths — ideal for item/price lines
`divider`	Full-width separator: `SOLID`, `DOTTED`, or `EMPTY`
`feed`	Advance paper N blank lines
`space`	Insert pixel-precise vertical whitespace
`cut`	Trigger the auto-cutter (silently ignored on cutterless terminals)
`image`	Print a Base64-encoded PNG/JPG — typically for merchant logos
`qr`	Generate a QR code natively in hardware
`barcode`	Generate a CODE128 barcode natively in hardware

{
  "printJobId": "RECEIPT-001",
  "webhookUrl": "https://pos.micomercio.pe/webhooks/print",
  "skipIfBusy": false,
  "commands": [
    { "type": "text", "text": "MI COMERCIO PERÚ\n", "align": "CENTER", "size": 32, "bold": true },
    { "type": "text", "text": "RUC: 20123456789\n", "align": "CENTER", "size": 20 },
    { "type": "divider", "dividerType": "SOLID" },
    { "type": "columns", "columns": [
        { "text": "Producto A", "weight": 2, "align": "LEFT" },
        { "text": "S/ 30.00",   "weight": 1, "align": "RIGHT" }
    ]},
    { "type": "divider", "dividerType": "DOTTED" },
    { "type": "columns", "columns": [
        { "text": "TOTAL", "weight": 2, "align": "LEFT" },
        { "text": "S/ 30.00", "weight": 1, "align": "RIGHT" }
    ]},
    { "type": "text", "text": "APROBADO\n", "align": "CENTER", "size": 28, "bold": true },
    { "type": "qr", "content": "https://micomercio.pe/boleta/4421", "dotSize": 6, "align": "CENTER" },
    { "type": "feed", "lines": 4 },
    { "type": "cut" }
  ]
}

How it works

All payment responses are synchronous — the terminal returns the result only once the EMV transaction is complete. Print jobs are asynchronous — the terminal responds immediately and you receive the result later.

── Payment flow ──────────────────────────────────────
1. POST /terminal/v1/[serial/]sync
   → Terminal reads card, processes EMV
   ← Returns result synchronously

2. Save rawResponse.transaction_reference
   → Required for void, refund, capture, re_authorization

── Print flow ────────────────────────────────────────
3. POST /terminal/v1/[serial/]sync/print/job  (Cloud)
   POST /terminal/v1/print                    (Local)
   ← 202 Accepted, status: PENDING

4. Terminal POSTs to webhookUrl  — OR —  you poll job_status
   ← status: COMPLETED | FAILED

Key concepts

`transaction_reference` — save it always

Every approved charge or authorization response includes a rawResponse.transaction_reference. Persist this value — it is required to void, refund, capture, or re-authorize that transaction later.

Idempotency

Every payment request must include a unique client_transaction_id (UUID v4). Reusing the same ID on a retry is safe — the terminal returns the original result without creating a duplicate.

Print jobs use printJobId for the same purpose. If omitted, the terminal auto-generates a UUID.

Void cutoff — Peru

Country	Cutoff
Peru 🇵🇪	20:59 local time

Void requests submitted after the cutoff are rejected. Use Refund instead for same-day transactions past the cutoff.

Amount object

The amount field does not include a currency — currency is configured at the terminal level in DMS.

"amount": {
  "iva": 0,
  "subtotal_iva": 0,
  "subtotal_iva0": 500
}

Tips, cashback, and installments

As of v1.2.0, tip and cashback amounts are configured in DMS and displayed by the terminal natively — they are no longer sent in the request body. Installment (deferred) options are also configured per terminal in DMS.

Terminal setup

Terminals are enrolled and configured through Kushki's Device Management System (DMS):

Setting	Description
Currency	Set at terminal level — not in request body
Tips & cashback	Configured in DMS (v1.2.0+)
Local IP	Assign a static IP or DHCP reservation
Port	Default `6868` (configurable in DMS)
Serial number	Used to identify terminal in Cloud mode URL

Supported hardware

Terminal	Chip (ICC)	Mag Stripe (MCR)	Contactless (NFC)	Thermal Printer
Sunmi P3	✅	✅	✅	✅ (384 px)
Sunmi P2 SE	✅	✅	✅	✅ (384 px)

Authentication

Both modes use HMAC-SHA256 — different from the Online Payments Private-Merchant-Id header.

Mode	Signing key
Cloud (Payment + Print)	`Private-Credential-Id`
Local (Payment only)	`Business-Code`
Local (Print)	No authentication required

WARNING

timestamp must be in milliseconds (13 digits). Seconds (10 digits) will be rejected.

Environments

🟢 Production (Cloud)

🧪 Sandbox (Cloud)

🔌 Local Network

https://cloudt.kushkipagos.com

Got a suggestion on this documentation? Contact us.

Connectivity modes#

Payment operations#

Transaction search#

Print operations#

Print command types#

How it works#

Key concepts#

transaction_reference — save it always#

Idempotency#

Void cutoff — Peru#

Amount object#

Tips, cashback, and installments#

Terminal setup#

Supported hardware#

Authentication#

Environments#

Connectivity modes

Payment operations

Transaction search

Print operations

Print command types

How it works

Key concepts

`transaction_reference` — save it always

Idempotency

Void cutoff — Peru

Amount object

Tips, cashback, and installments

Terminal setup

Supported hardware

Authentication

Environments