Cloud Services

In Cloud mode, your POS sends HTTP requests to Kushki's cloud infrastructure, which forwards the commands to the target terminal via push. Use this mode when your POS runs in the cloud or on a network that cannot route traffic directly to the terminal.

Beta — Early Access

Kushki ONE Cloud is currently in Beta for Chile 🇨🇱. Do not deploy to production without coordinating with the Kushki integration team.

Base URLs

Environment	URL
Production	`https://cloudt.kushkipagos.com`
UAT	`https://uat-cloudt.kushkipagos.com`

All endpoints follow the pattern:

POST https://cloudt.kushkipagos.com/terminal/v1/{terminalSerial}/sync/{operation}

The terminalSerial is the serial number of the target SmartPOS terminal, obtained from the Device Management System (DMS).

Authentication

All Cloud requests require two signed headers:

Header	Description
`Authorization`	HMAC-SHA256 signature of the raw JSON request body, Base64-encoded. Key = your `Business-Code`
`timestamp`	Current Unix timestamp in milliseconds (13 digits) — must be within ±5 minutes of server time

ℹ️ Omit Authorization on requests with no body (e.g. Abort).

Payment operations

Operation	Endpoint	Description
Charge	`POST /sync/charge`	One-step authorization + capture
Authorization	`POST /sync/authorization`	Reserve funds, capture later (Visa / Mastercard)
Capture	`POST /sync/capture`	Collect reserved funds
Re-authorization	`POST /sync/re_authorization`	Extend or increase a pre-auth
Post-tip	`POST /sync/pos_tip`	Add tip to an authorized transaction
Void	`POST /sync/void`	Cancel same-day transaction (cutoff: 23:59 local)
Refund	`POST /sync/refund`	Refund a settled transaction
Abort	`POST /sync/abort`	Cancel a transaction in progress
Transaction Search	`POST /sync/transaction_search`	Query terminal transaction history

Charge

Single-step payment — authorization and capture in one operation.

{
  "amount": {
    "subtotal_iva0": 10000,
    "subtotal_iva": 0,
    "iva": 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"
  }
}

⚠️ Save transaction_reference from the response — required for void or refund.

Authorization (Pre-auth)

Reserves funds without capturing. Use for hotels, gas stations, or open-tab scenarios.

{
  "amount": {
    "subtotal_iva0": 10000,
    "subtotal_iva": 0,
    "iva": 0
  },
  "client_transaction_id": "auth-20240317-001"
}

Capture

Collects funds reserved by a prior authorization. Amount must be ≤ 110% of the authorized amount.

{
  "transaction_reference": "6f16659e-b711-4995-a9ae-161aecbd6521",
  "amount": {
    "subtotal_iva0": 10000,
    "subtotal_iva": 0,
    "iva": 0
  }
}

Void

Cancels a same-day transaction before the processor cutoff. Wait at least 1 minute after the original transaction.

{
  "transaction_reference": "6f16659e-b711-4995-a9ae-161aecbd6521"
}

Refund

Refunds a captured and settled transaction — can be executed days after the charge.

{
  "transaction_reference": "6f16659e-b711-4995-a9ae-161aecbd6521",
  "amount": {
    "subtotal_iva0": 10000,
    "subtotal_iva": 0,
    "iva": 0
  }
}

Transaction Search

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

Print operations

Operation	Endpoint	Description
Create Print Job	`POST /sync/print/job`	Queue a print job on the terminal printer
Get Print Job Status	`POST /sync/print/job_status`	Poll the status of a queued print job

Printing is asynchronous — the create endpoint returns 202 Accepted immediately. Supply a webhookUrl or poll for the result.

Create Print Job

{
  "webhookUrl": "https://yoursite.com/print/notify",
  "commands": [
    { "type": "TEXT", "text": "MI COMERCIO CHILE", "align": "CENTER", "size": 32, "bold": true },
    { "type": "DIVIDER", "style": "SOLID" },
    { "type": "COLUMNS", "columns": [
        { "text": "Producto Premium", "width": 3 },
        { "text": "10.000", "width": 1, "align": "RIGHT" }
    ]},
    { "type": "DIVIDER", "style": "DOTTED" },
    { "type": "COLUMNS", "columns": [
        { "text": "TOTAL", "width": 3, "bold": true },
        { "text": "10.000", "width": 1, "align": "RIGHT", "bold": true }
    ]},
    { "type": "FEED", "lines": 2 },
    { "type": "CUT" }
  ]
}

Response:

{
  "print_job_id": "pj_a1b2c3d4e5f6",
  "status": "PENDING"
}

Get Print Job Status

{
  "print_job_id": "pj_a1b2c3d4e5f6"
}

Status	Description
`PENDING`	Job queued — not yet printed
`COMPLETED`	Printed successfully
`FAILED`	Printing failed

Available Endpoints

Charge

One-step authorization + capture.

Authorization

Reserve funds for later capture.

Capture

Collect reserved funds from a prior authorization.

Re-authorization

Extend or increase a pre-authorization.

Post-tip

Add gratuity to an authorized transaction.

Void

Cancel a same-day transaction before cutoff.

Refund

Refund a settled transaction.

Abort

Cancel a transaction currently in progress on the terminal.

Transaction Search

Query terminal transaction history.

Create Print Job

Queue a print job. Returns immediately — result via webhook or polling.

Get Print Job Status

Poll the status of a queued print job.

Got a suggestion on this documentation? Contact us.

Base URLs#

Authentication#

Payment operations#

Charge#

Authorization (Pre-auth)#

Capture#

Void#

Refund#

Transaction Search#

Print operations#

Create Print Job#

Get Print Job Status#

Available Endpoints#

Base URLs

Authentication

Payment operations

Charge

Authorization (Pre-auth)

Capture

Void

Refund

Transaction Search

Print operations

Create Print Job

Get Print Job Status

Available Endpoints