Local Services

In Local Network mode, your POS sends HTTP requests directly to the terminal's local IP address over your LAN or Wi-Fi. Use this mode when your POS and terminal share the same network and you want the lowest latency with no cloud dependency.

Beta — Early Access

Kushki ONE Local Network is currently in Beta for Perú 🇵🇪. Do not deploy to production without coordinating with the Kushki integration team.

Base URL

The terminal exposes an HTTP server on its local IP, on two ports:

http://{terminalIp}:6868/terminal/v1     ← HTTP
https://{terminalIp}:6869/terminal/v1    ← HTTPS

Variable	Default	Description
`terminalIp`	`192.168.1.50`	Static IP or DHCP reservation of the terminal. The integration team gives you the terminal's addressing during onboarding
`port`	`6868` HTTP · `6869` HTTPS	Both are open on the terminal

Payment operations live under /sync/ and /async/, so a charge is POST http://192.168.1.50:6868/terminal/v1/sync/charge. Print keeps its own paths — see below.

WARNING

Your internal firewall must allow bidirectional traffic on both TCP ports of the terminal: 6868 for HTTP and 6869 for HTTPS. A network that only opens 6868 blocks HTTPS access to the terminal.

INFO

Select the Kushki ONE Local environment at the top right, then override terminalIp and port with your own terminal's values. The default UAT Testing Env points at api-uat.kushkipagos.com, which is the Online Payments host — a local terminal does not answer there.

There is no UAT/production split in Local mode: you always call the same device on your network. Whether it settles against the UAT or the production acquirer is decided by how the terminal itself was provisioned, not by the URL.

WARNING

On port 6868 the transport is plain HTTP, though the payload itself always travels encrypted (see Authentication). Use 6869 when you need TLS on the wire as well, and keep the terminal on a trusted, segmented network either way. The terminal still needs port 443 egress to reach Kushki's authorization servers.

Authentication

Kushki ONE uses one authentication mechanism, and it is the same in local network, Cloud and localhost: hash + encryption. Your terminal ships with encryption enabled, so this is the only path. Both headers are required on every endpoint, print included.

{ "data": "<iv_hex>:<cipher_hex>" }

Element	Rule
`Authorization`	`Basic` prefix followed by the SHA512 hash. The `Basic` prefix is required
`timestamp`	Unix timestamp in seconds (10 digits) — must be within ±5 minutes of server time
Body	Always the encrypted envelope `{"data":"<iv_hex>:<cipher_hex>"}`. The payloads documented below are the plaintext you encrypt, not what travels on the wire

WARNING

Two cases that return UNAUTHORIZED with no further hint:

GET operations — /sync/abort, /async/abort and GET /terminal/v1/print_job. The encrypted value travels as the data query parameter, and no other parameter may be sent.

Operations with no payload — on abort you sign the literal {}, not an empty string.

Full details are on the Authentication page.

Sync vs Async

Every payment operation ships in two variants under two path prefixes.

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	Webhook only

Async exists because card-present flows wait on a human and routinely exceed the ~15 second timeout budget of most POS architectures. Supply events_webhook_url in the body to receive events; it is accepted on /async/ endpoints only.

Both transaction searches are sync-only. Everything else, abort included, exists in both variants.

Reading the HTTP status

DANGER

On payment endpoints the HTTP status is always 200, whatever happened. It confirms that the terminal processed your request — not that the operation succeeded. Always evaluate the response body.

A POS that branches on response.ok treats a busy terminal, an expired PIN and a cardholder cancellation as successes. The print endpoints are the exception: they return real HTTP codes (404 when the job does not exist, 409 while the printer is busy).

Error bodies are flat — {type, code, param, message, object}, with no wrapper. See the Error Catalog.

Amount format

Every amount field is an integer in céntimos. The terminal is provisioned in PEN or USD, both with two decimal places — the last two digits are always the fractional part, so amounts without a fraction keep their trailing zeros:

To charge	Send
S/ 12.44	`1244`
S/ 12.00	`1200`

This applies to subtotal_iva0, subtotal_iva, iva, tip, cashback_amount and every member of extra_taxes. There is no currency field — the terminal resolves the currency from its own configuration, and the integration team confirms which one your terminal uses during onboarding.

WARNING

Requests take integers, but event and webhook payloads echo amounts back as decimals (12000.0). Never re-send an echoed value as an amount.

Payment operations

Operation	Sync	Async
Charge	`POST /sync/charge`	`POST /async/charge`
Authorization	`POST /sync/authorization`	`POST /async/authorization`
Capture	`POST /sync/capture`	`POST /async/capture`
Re-authorization	`POST /sync/re_authorization`	`POST /async/re_authorization`
Post-tip	`POST /sync/pos_tip`	`POST /async/pos_tip`
Reversal	`POST /sync/void`	`POST /async/void`
Abort	`GET /sync/abort`	`GET /async/abort`
Transaction Search — Online	`POST /sync/transaction_search_online`	—
Transaction Search — Local	`POST /sync/transaction_search_local`	—
Connection test	`GET /sync/local/test`	—
Terminal info	`GET /sync/config/terminal_info`	—

Optional fields, by operation

These are the only optional fields, and they are the same in sync and async:

Field	Applies to
`amount.tip`	`/charge` and `/authorization` — the tip can be set at pre-authorization time, not only when charging
`cashback_amount`	`/charge`
`deferred`	`/charge` — installments
`omit_card`	`/capture`, `/re_authorization` and `/void`
`metadata`	`/charge`, `/authorization` and `/pos_tip`. Subfields: `reference`, `customer_email`, `device`

On /pos_tip, amount.tip is not an optional field — it is the amount of the operation.

omit_card decides whether the terminal asks the cardholder for the card. With true the operation runs without it — which is what makes the hotel case work: extending or capturing a pre-authorization after the guest has left the desk.

In Peru, installments travel in the deferred object — {"deferred": {"months": 12}}. Your POS sends the number of months: 2 to 48, the same range for every card network. query_deferred is Mexico only and must not be sent from Peru; the two fields are mutually exclusive.

If a capability is not enabled for your terminal, the terminal ignores the field instead of rejecting the request. To have it enabled, write to soporte@kushkipagos.com.

INFO

Beta coverage. Only /charge has been exercised end-to-end with these fields, in sync and async. amount.tip on /authorization and omit_card on its six combinations are defined but not yet exercised.

Charge

{
  "amount": {
    "subtotal_iva0": 10000,
    "subtotal_iva": 0,
    "iva": 0,
    "tip": 0,
    "extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 }
  },
  "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af79",
  "metadata": { "reference": "ORD-20240317-001", "customer_email": "user@example.com", "device": "SUNMI-P3" }
}

⚠️ Save rawResponse.transaction_reference from the response — required for capture, re-authorization and void.

Two-step flow

authorization ──→ re_authorization (0..n) ──→ capture
      │                                          │
      └──────────────→ void ←───────────────────┘

Rule	Detail
Pre-auth validity	Debit 7 days, credit 28 days. Visa and Mastercard only
Capture ceiling	≤ 110% of the authorization plus all non-canceled re-authorizations
Captures per cycle	Exactly one
Reversal window	The same calendar day as the original transaction, cutoff 23:59 local

Reversal (`/void`)

There is one reversal endpoint, and the system decides what the operation becomes based on when you call it. Within the same calendar day the reversal is a cancellation; from midnight onwards it enters the refund cycle and takes business days. Wait at least 1 minute after the original transaction before reversing it.

The type returned by transaction search tells you what actually happened: VOID for a same-day cancellation, REFUND for one that entered the refund cycle, and REVERSE for one you did not ask for — the platform generates it on its own when communication with the terminal fails. A POS can find a REVERSE in search that it never requested; it is not an error.

Transaction Search

Two endpoints, different backends: _online queries the Kushki acquirer and needs internet; _local reads what the terminal itself stored and works offline.

{
  "page": 1,
  "size": 10,
  "filters": { "last_four_digits": "9130", "start_date": 0, "end_date": 0 }
}

Filters shared by both: bin, last_four_digits, client_transaction_id, transaction_reference, start_date and end_date. Beyond those, _online filters by transaction_type and _local by status.

Dates are 13-digit millisecond timestamps. Send 0 in both to disable date filtering.

DANGER

A 10-digit value in seconds lands in January 1970. If only start_date is wrong, the request succeeds and returns your entire history instead of the range you asked for — check the digit count before you reconcile.

WARNING

The two endpoints do not return the same shape. They share no envelope, no casing and no field names:

_online returns {"items": [...]} in snake_case, with no pagination metadata — it accepts page and size but does not tell you whether more pages exist.

_local returns {"rawResponse": {"data": [...], "totalElements": 2, "totalPages": 1}} in camelCase.

The same field changes name between them: client_transaction_id / clientTransactionId, transaction_status / eventStatus, transaction_type / type, payment_brand / franchise, created / date. Write one parser per endpoint.

Print operations

Operation	Endpoint
Create Print Job	`POST /terminal/v1/print`
Get Print Job Status	`GET /terminal/v1/print_job?data=…`

Printing is asynchronous — create returns 202 Accepted with PENDING. Track the outcome by polling the status endpoint, or by supplying a webhookUrl and implementing that endpoint on your side — it is a callback you receive, not an endpoint Kushki exposes.

Write type in lowercase; every other enum (align, dividerType, algorithm, errorLevel) is UPPERCASE.

{
  "printJobId": "RECEIPT-20240317-001",
  "webhookUrl": "https://pos.yourstore.com/webhooks/print",
  "commands": [
    { "type": "text", "text": "MI COMERCIO PERÚ\n", "align": "CENTER", "size": 28, "bold": true },
    { "type": "divider", "dividerType": "SOLID", "offset": 8 },
    { "type": "columns", "columns": [
        { "text": "2x Combo Hamburguesa", "weight": 2, "align": "LEFT" },
        { "text": "S/ 300.00", "weight": 1, "align": "RIGHT" }
    ]},
    { "type": "feed", "lines": 3 },
    { "type": "cut" }
  ]
}

Status	Description
`PENDING`	Queued, not yet printed
`IN_PROGRESS`	The driver is sending commands to the printer
`COMPLETED`	Printed and cut successfully
`FAILED`	Hardware error — see `errorCode`

INFO

A TER-004 on the print endpoints means the printer is busy and the job can be retried in a few seconds. The same code on a payment endpoint means the cardholder canceled on the terminal, which must not be retried.

Key differences from Cloud mode

Feature	Local Network	Cloud
Base URL	`http://{terminalIp}:6868/terminal/v1` or `https://{terminalIp}:6869/terminal/v1`	`https://cloudt.kushkipagos.com`
Terminal addressing	The terminal's IP	`terminalSerial` in the path
Abort method	`GET /sync/abort`, `GET /async/abort`	`POST /sync/abort`, sync only
Async abort	✅	❌
Transaction search	Two endpoints: `_online` and `_local`	`_online` only
Print create	`POST /terminal/v1/print`	`POST /{terminalSerial}/sync/print`
Print status	`GET /terminal/v1/print_job?data=`	`POST /{terminalSerial}/sync/print_job` with the ID in the body
Recommended HTTP timeout	15 s	90 s (relay latency)
Network requirement	Terminal and POS on the same LAN/Wi-Fi	Internet access

Payloads and headers are identical between the two modes. The routes are not.

Folders

Payment

16 card operations, sync and async.

Receipt printing on the terminal's thermal printer.

Got a suggestion on this documentation? Contact us.

Base URL#

Authentication#

Sync vs Async#

Reading the HTTP status#

Amount format#

Payment operations#

Optional fields, by operation#

Charge#

Two-step flow#

Reversal (/void)#

Transaction Search#

Print operations#

Key differences from Cloud mode#

Folders#

Base URL

Authentication

Sync vs Async

Reading the HTTP status

Amount format

Payment operations

Optional fields, by operation

Charge

Two-step flow

Reversal (`/void`)

Transaction Search

Print operations

Key differences from Cloud mode

Folders