Cloud Services

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

Beta

Kushki ONE Cloud 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 (e.g., if the customer walks away mid-flow).

Transaction Search

Query the transaction history stored in Kushki's acquirer backend with date and filter parameters.

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 status of a queued print job. Use when your system cannot receive inbound webhook connections.

Request structure

All payment operations share the same endpoint. 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 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.

Terminal identification (Cloud)

The terminal is identified by its serial number in the URL path:

POST /terminal/v1/SN71652/sync

The serial number is assigned by DMS when the terminal is enrolled.

Authentication

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

WARNING

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

Environments

🟢 Production

🧪 Sandbox (UAT)

https://cloudt.kushkipagos.com

Got a suggestion on this documentation? Contact us.

Available operations#

Payment API#

Print API#

Request structure#

Key concepts#

transaction_reference — save it always#

Idempotency#

Void cutoff — Peru#

Pre-authorization lifecycle#

Terminal identification (Cloud)#

Authentication#

Environments#

Available operations

Payment API

Print API

Request structure

Key concepts

`transaction_reference` — save it always

Idempotency

Void cutoff — Peru

Pre-authorization lifecycle

Terminal identification (Cloud)

Authentication

Environments