Local Services

Kushki ONE Local Network lets your POS communicate directly with the SmartPOS terminal over your local LAN or Wi-Fi — no internet required for the connection itself. Your server calls the terminal's IP address, the terminal processes the transaction using its EMV kernel and acquirer connection, and returns the result synchronously.

Beta

Kushki ONE Local Network is in Beta phase. Contact your account manager before deploying to production.

Available operations

Payment API

Charge

Single or deferred card charge in one step. Supports tip and cashback flows.

Authorization

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

Capture

Capture a previously authorized amount. Maximum capture = 110% of the total authorized (including re-authorizations).

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 the transaction_reference from the original response.

Abort

Cancel a transaction currently in progress on the terminal.

Transaction Search (Online)

Query the transaction history from Kushki's acquirer backend — full history with status and amounts.

Transaction Search (Local)

Query transactions stored on the terminal itself — works offline, limited to the terminal's local storage window.

POS Tip

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

Print API

Create Print Job

Send an ordered list of print commands to the terminal's thermal printer. Returns 202 immediately — printing is asynchronous.

Get Print Job Status

Poll the current status of a queued print job.

Print Job Webhook

The terminal POSTs to your webhookUrl when a print job completes or fails. Implement this endpoint in your POS system.

Terminal setup

Before making API calls, the terminal must be configured in DMS:

Setting	Description
Static IP / DHCP reservation	Assign a fixed IP to the terminal on your local network
Port	Default `6868` (configurable in DMS)
Currency	Set at terminal level in DMS — not sent in request body
Tips & cashback	Configured in DMS (v1.2.0+) — not sent in request body

The base URL is:

http://{terminalIp}:{port}

Default example: http://192.168.1.50:6868

Request structure

All payment operations share the same endpoint path. The transaction_type and transaction_mode fields determine the operation:

{
  "transaction_type": "charge",
  "transaction_mode": "Authorization",
  "client_transaction_id": "<uuid-v4>",
  "amount": {
    "iva": 0,
    "subtotal_iva": 0,
    "subtotal_iva0": 500
  }
}

INFO

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

Key concepts

`transaction_reference` — save it always

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

Idempotency

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

Void cutoff — Peru

Country	Cutoff
Peru 🇵🇪	20:59 local time
Colombia	23:59 local time
Chile	23:59 local time

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

Online vs Local transaction search

	Transaction Search (Online)	Transaction Search (Local)
Source	Kushki acquirer backend	Terminal local storage
Works offline	❌	✅
Full history	✅	Limited to terminal storage window
Use case	Reconciliation, reporting	Same-day recovery, offline fallback

Pre-authorization lifecycle

Card type	Maximum hold	Capture limit
Debit	7 days	110% of total authorized
Credit	28 days	110% of total authorized

Only one capture is allowed per authorization cycle. Multiple re-authorizations are permitted before capture.

Authentication

Payment API (HMAC-SHA256)

Sign the raw request body bytes using HMAC-SHA256. The key is your Business-Code (different from Cloud mode, which uses Private-Credential-Id). Encode the binary digest as Base64.

WARNING

The timestamp header must be in milliseconds (13 digits), not seconds.

Print API — no authentication required

Print API calls are made directly over the local network and do not require Authorization or timestamp headers. Authentication is provided by network-level access control — only devices on the local network can reach the terminal.

Environments

🔌 Local Network

http://{terminalIp}:6868

Point directly at your terminal's IP address. There is no separate UAT URL — connect to your designated test terminal.

Got a suggestion on this documentation? Contact us.

Available operations#

Payment API#

Print API#

Terminal setup#

Request structure#

Key concepts#

transaction_reference — save it always#

Idempotency#

Void cutoff — Peru#

Online vs Local transaction search#

Pre-authorization lifecycle#

Authentication#

Payment API (HMAC-SHA256)#

Print API — no authentication required#

Environments#

Available operations

Payment API

Print API

Terminal setup

Request structure

Key concepts

`transaction_reference` — save it always

Idempotency

Void cutoff — Peru

Online vs Local transaction search

Pre-authorization lifecycle

Authentication

Payment API (HMAC-SHA256)

Print API — no authentication required

Environments