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 local network and you want the lowest latency with no cloud dependency.

Beta — Early Access

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

Base URL

The terminal exposes an HTTP server on its local IP:

http://{terminalIp}:{port}/terminal/v1/sync

Variable	Default	Description
`terminalIp`	`192.168.1.50`	Static IP or DHCP reservation of the terminal
`port`	`6868`	Configured in the Device Management System (DMS)

Authentication

Payment API 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). The Print API does not require authentication headers.

Payment operations

Operation	Endpoint	Description
Charge	`POST /charge`	One-step authorization + capture
Authorization	`POST /authorization`	Reserve funds, capture later (Visa / Mastercard)
Capture	`POST /capture`	Collect reserved funds
Re-authorization	`POST /re_authorization`	Extend or increase a pre-auth
Post-tip	`POST /pos_tip`	Add tip to an authorized transaction
Void	`POST /void`	Cancel same-day transaction (cutoff: 23:59 local)
Refund	`POST /refund`	Refund a settled transaction
Abort	`GET /abort`	Cancel a transaction in progress
Transaction Search (online)	`POST /transaction_search_online`	Query online transaction history
Transaction Search (local)	`POST /transaction_search_local`	Query offline/fallback 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
  }
}

Re-authorization

Extends the reserved amount or validity of an existing pre-authorization.

Goal	`subtotal_iva0` value
Extend validity only	`0`
Increase reserved amount	New total amount

Post-tip

Adds a tip to an already-authorized transaction.

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

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
  }
}

Abort

Immediately cancels a transaction in progress. No request body — uses GET /abort.

⚠️ Only call Abort while a transaction is active. Calling after completion has no effect and may return an error.

Transaction Search

Local Network mode exposes two separate search endpoints:

Endpoint	Description
`POST /transaction_search_online`	Transactions processed online (standard flow)
`POST /transaction_search_local`	Transactions processed offline or in fallback mode

{
  "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 /terminal/v1/print`	Queue a print job on the terminal printer
Get Print Job Status	`GET /terminal/v1/print_job?print_job_id={id}`	Poll the status of a queued print job
Print Job Webhook	—	Inbound endpoint on your POS — receives completion events from the terminal

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

ℹ️ The Print API does not require Authorization or timestamp headers.

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": "QR", "data": "https://yoursite.com/receipt/12345", "size": 6 },
    { "type": "CUT" }
  ]
}

Response:

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

Get Print Job Status

GET /terminal/v1/print_job?print_job_id=pj_a1b2c3d4e5f6

Status	Description
`PENDING`	Job queued — not yet printed
`COMPLETED`	Printed successfully
`FAILED`	Printing failed (paper jam, out of paper, etc.)

Print Job Webhook

Supply a webhookUrl in the Create Print Job request. When printing finishes, the terminal POSTs to your URL:

{
  "print_job_id": "pj_a1b2c3d4e5f6",
  "print_job_status": "COMPLETED"
}

Implement this endpoint in your POS to receive print job completion events without polling.

Key differences from Cloud mode

Feature	Local Network	Cloud
Abort method	`GET /abort` (no body)	`POST /sync/abort`
Transaction search	Two endpoints: `_online` and `_local`	Single `transaction_search` endpoint
Print base path	`/terminal/v1/print`	`/terminal/v1/{terminalSerial}/sync/print/job`
Print status	`GET /terminal/v1/print_job?print_job_id=`	`POST /sync/print/job_status`
Webhook support	✅ Terminal pushes to your POS	✅ Kushki cloud pushes to your POS
Network requirement	Terminal and POS on same LAN/Wi-Fi	Internet access

Available Endpoints

Charge

One-step authorization + capture over local network.

Authorization

Reserve funds for later capture over local network.

Capture

Collect reserved funds from a prior authorization.

Re-authorization

Extend or increase a pre-authorization over local network.

Post-tip

Add gratuity to an authorized transaction over local network.

Void

Cancel a same-day transaction before cutoff over local network.

Refund

Refund a settled transaction over local network.

Abort

Cancel an in-progress transaction via GET over local network.

Transaction Search (Online)

Query online transaction history over local network.

Transaction Search (Local)

Query offline/fallback transaction history over local network.

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 over local network.

Print Job Webhook

Inbound webhook — implement this in your POS to receive print completion events.

Got a suggestion on this documentation? Contact us.

Base URL#

Authentication#

Payment operations#

Charge#

Authorization (Pre-auth)#

Capture#

Re-authorization#

Post-tip#

Void#

Refund#

Abort#

Transaction Search#

Print operations#

Create Print Job#

Get Print Job Status#

Print Job Webhook#

Key differences from Cloud mode#

Available Endpoints#

Base URL

Authentication

Payment operations

Charge

Authorization (Pre-auth)

Capture

Re-authorization

Post-tip

Void

Refund

Abort

Transaction Search

Print operations

Create Print Job

Get Print Job Status

Print Job Webhook

Key differences from Cloud mode

Available Endpoints