Local Services

Kushki ONE Local Services let your POS communicate directly with the SmartPOS terminal over your local LAN or Wi-Fi. Your server calls the terminal's IP address, the terminal processes the request using its EMV kernel and acquirer connection, and returns the result synchronously.

Beta

Kushki ONE Local Services are in Beta phase for Colombia 🇨🇴. Contact your account manager before deploying to production.

Three APIs are available in Local Network mode:

API	What it does	Auth
Payments API	Card payments — charge, pre-auth, capture, void, refund, and more	HMAC-SHA256 (`Business-Code`)
Transaction Search	Query transactions from the backend (online) or from terminal storage (offline)	HMAC-SHA256 (`Business-Code`)
Print API	Send structured receipt jobs to the terminal's thermal printer	None

Terminal setup

Before making API calls, configure the terminal 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 — not sent in the request body
Tips & cashback	Configured in DMS (v1.2.0+) — not sent in the request body

Base URL:

http://{terminalIp}:{port}

Default example: http://192.168.1.50:6868

Payments API

Available operations

Charge

Single or deferred card charge in one step. Tip and cashback are 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. Colombia cutoff: 23:59 local time.

Refund

Refund a settled transaction — full or partial. Requires transaction_reference from the original charge or authorization 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 before charging.

Payment request structure

All payment operations use the same endpoint. transaction_type and transaction_mode determine the operation:

{
  "transaction_type": "charge",
  "transaction_mode": "Authorization",
  "client_transaction_id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": {
    "iva": 19000,
    "subtotal_iva": 100000,
    "subtotal_iva0": 0
  }
}

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. Persist this value — it is required to void, refund, capture, or re-authorize that transaction.

Void cutoff — Colombia

Country	Cutoff
Colombia 🇨🇴	23:59 local time
Peru	20:59 local time
Chile	23:59 local time

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

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.

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.

Tips, cashback, and installments

As of v1.2.0, tip and cashback amounts are configured in DMS and entered by the customer on the terminal natively — they are not sent in the request body. Installment options are also configured per terminal in DMS.

Transaction Search

Local Network mode provides two transaction search endpoints — choose based on your connectivity situation:

Transaction Search (Online)

Queries Kushki's acquirer backend. Returns full transaction history with all statuses and amounts. Requires internet connectivity.

Transaction Search (Local)

Queries transactions stored on the terminal itself. Works offline — no internet required. Limited to the terminal's local storage window.

Online vs Local — when to use each

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

Request structure (Online)

{
  "from": "2026-01-01T00:00:00",
  "to": "2026-01-31T23:59:59",
  "page": 1,
  "page_size": 50
}

Request structure (Local)

{
  "from": "2026-01-01T00:00:00",
  "to": "2026-01-01T23:59:59",
  "page": 1,
  "page_size": 50
}

Print API

Control the terminal's thermal printer directly over the local network. Print jobs are asynchronous — the terminal returns 202 Accepted immediately and delivers the final status via webhook or polling.

INFO

The Print API does not require authentication — requests are trusted based on local network access.

Available operations

Create Print Job

Send an ordered commands array to the terminal's thermal printer. Returns 202 immediately — printing executes asynchronously.

Get Print Job Status

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

Print Job Webhook

Endpoint in your POS system that receives the async result when a job finishes. The terminal POSTs here when the job completes or fails. Implement this to avoid polling.

Print request structure

{
  "printJobId": "RECEIPT-20260101-001",
  "webhookUrl": "https://pos.micomercio.co/webhooks/print",
  "skipIfBusy": false,
  "commands": [
    { "type": "text",    "text": "MI COMERCIO COLOMBIA\n", "align": "CENTER", "size": 32, "bold": true },
    { "type": "text",    "text": "NIT: 900.123.456-7\n",   "align": "CENTER", "size": 20 },
    { "type": "divider", "dividerType": "SOLID" },
    { "type": "columns", "columns": [
        { "text": "Producto A", "weight": 2, "align": "LEFT" },
        { "text": "$ 30.000",   "weight": 1, "align": "RIGHT" }
    ]},
    { "type": "divider", "dividerType": "DOTTED" },
    { "type": "columns", "columns": [
        { "text": "TOTAL",    "weight": 2, "align": "LEFT" },
        { "text": "$ 30.000", "weight": 1, "align": "RIGHT" }
    ]},
    { "type": "text", "text": "APROBADO\n", "align": "CENTER", "size": 28, "bold": true },
    { "type": "qr",  "content": "https://micomercio.co/factura/001", "dotSize": 6, "align": "CENTER" },
    { "type": "feed", "lines": 4 },
    { "type": "cut" }
  ]
}

Print command types

`type`	Description
`text`	Text line — 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 (max 384 px wide)
`qr`	Generate a QR code natively in hardware
`barcode`	Generate a CODE128 barcode natively in hardware

Print best practices

Practice	Reason
Always end with `feed` (≥ 3 lines) + `cut`	Ensures content clears the tear edge before cutting
Always set `printJobId`	Enables idempotent retries — terminal deduplicates by this ID
Set `skipIfBusy: false` for payment receipts	Prevents a busy queue from silently discarding a receipt
Use `BINARIZATION` algorithm for logos	Sharper edges on monochrome thermal paper
Use `qr` / `barcode` over `image` for codes	Native hardware generation is faster and higher density

Print webhook payload

When the job finishes, the terminal POSTs to your webhookUrl:

{
  "printJobId": "RECEIPT-20260101-001",
  "status": "COMPLETED",
  "externalReference": "Order-4421"
}

On failure:

{
  "printJobId": "RECEIPT-20260101-001",
  "status": "FAILED",
  "externalReference": "Order-4421",
  "errorCode": "OUT_OF_PAPER",
  "errorMessage": "The printer is out of paper. Insert a roll and try again."
}

Your webhook endpoint must return HTTP 2xx. If the webhook does not arrive within ~60 seconds, use GET /terminal/v1/print_job?print_job_id={id} as fallback.

Authentication

API	Header	Key
Payments API	`Authorization` + `timestamp`	`Business-Code`
Transaction Search	`Authorization` + `timestamp`	`Business-Code`
Print API	—	No authentication required

Sign the raw request body bytes using HMAC-SHA256. The key is your Business-Code.

WARNING

timestamp must be in milliseconds (13 digits). A 10-digit seconds value will be rejected.

The signing key for Local mode is Business-Code — different from Cloud mode, which uses Private-Credential-Id.

Environments

🔌 Local Network

http://{terminalIp}:6868

Connect directly to your terminal's IP address. There is no separate UAT URL — use a designated test terminal.

Got a suggestion on this documentation? Contact us.

Terminal setup#

Payments API#

Available operations#

Payment request structure#

Key concepts#

transaction_reference — save it always#

Void cutoff — Colombia#

Pre-authorization lifecycle#

Idempotency#

Tips, cashback, and installments#

Transaction Search#

Online vs Local — when to use each#

Request structure (Online)#

Request structure (Local)#

Print API#

Available operations#

Print request structure#

Print command types#

Print best practices#

Print webhook payload#

Authentication#

Environments#

Terminal setup

Payments API

Available operations

Payment request structure

Key concepts

`transaction_reference` — save it always

Void cutoff — Colombia

Pre-authorization lifecycle

Idempotency

Tips, cashback, and installments

Transaction Search

Online vs Local — when to use each

Request structure (Online)

Request structure (Local)

Print API

Available operations

Print request structure

Print command types

Print best practices

Print webhook payload

Authentication

Environments