Cloud Services

Kushki ONE Cloud Services let your backend communicate with the SmartPOS terminal through Kushki's cloud relay. Your server calls cloudt.kushkipagos.com, Kushki routes the command to the terminal identified by its serial number, and the terminal returns the result synchronously.

Beta

Kushki ONE Cloud Services are in Beta phase. Contact your account manager before deploying to production.

Three APIs are available in Cloud mode:

API	What it does
Payments API	Card payments — charge, pre-authorization, capture, void, refund, and more
Transaction Search	Query the full transaction history from Kushki's acquirer backend
Print API	Send structured receipt jobs to the terminal's thermal printer

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

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

Query the full transaction history stored in Kushki's acquirer backend. Supports filtering by date range, terminal serial, card BIN, last four digits, and transaction reference.

Transaction Search

Returns a paginated list of transactions processed by the authenticated merchant. Source: Kushki acquirer backend — full history, all statuses.

Request structure

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

INFO

Transaction Search queries Kushki's acquirer backend and requires internet connectivity. For offline or same-day recovery, use the Local Transaction Search available in Local Network mode.

Print API

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

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 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
Always set `printJobId`	Enables idempotent retries — terminal deduplicates
Set `skipIfBusy: false` for payment receipts	Prevents a busy queue from silently discarding the receipt
Use `BINARIZATION` algorithm for logos	Sharper edges on monochrome thermal paper
Set HTTP timeout ≥ 15 s	Cloud relay adds latency before the `202` response

Authentication

All Cloud Services use the same HMAC-SHA256 authentication scheme:

Sign the raw request body bytes using HMAC-SHA256. The key is your Private-Credential-Id. Encode the binary digest as Base64.

WARNING

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

Terminal identification

In Cloud mode, the terminal is identified by its serial number in the URL path — assigned by DMS when the terminal is enrolled:

POST /terminal/v1/SN71652/sync
POST /terminal/v1/SN71652/sync/print/job
POST /terminal/v1/SN71652/sync/transaction/search

Environments

🟢 Production

🧪 Sandbox (UAT)

https://cloudt.kushkipagos.com

Got a suggestion on this documentation? Contact us.

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#

Request structure#

Print API#

Available operations#

Print request structure#

Print command types#

Print best practices#

Authentication#

Terminal identification#

Environments#

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

Request structure

Print API

Available operations

Print request structure

Print command types

Print best practices

Authentication

Terminal identification

Environments