Payment

The Payment API lets your POS system control all card payment operations on a Kushki SmartPOS terminal in Chile 🇨🇱. The same operations are available in both Cloud and Local Network modes — only the base URL changes.

Beta — Early Access

This API is in early access. Endpoints, parameters, and response structures may change without prior notice. Do not deploy to production without coordinating with the Kushki integration team.

Operations

Operation	Cloud endpoint	Local endpoint	Description
Charge	`POST /sync/charge`	`POST /charge`	One-step authorization + capture
Authorization	`POST /sync/authorization`	`POST /authorization`	Reserve funds, capture later
Capture	`POST /sync/capture`	`POST /capture`	Collect reserved funds
Re-authorization	`POST /sync/re_authorization`	`POST /re_authorization`	Extend or increase a pre-auth
Post-tip	`POST /sync/pos_tip`	`POST /pos_tip`	Add tip to an authorized transaction
Void	`POST /sync/void`	`POST /void`	Cancel a same-day transaction
Refund	`POST /sync/refund`	`POST /refund`	Refund a settled transaction
Abort	`POST /sync/abort`	`GET /abort`	Cancel a transaction in progress
Transaction Search	`POST /sync/transaction_search`	`POST /transaction_search_online` / `POST /transaction_search_local`	Query terminal transaction history

ℹ️ Cloud path prefix: /terminal/v1/{terminalSerial}/sync/{operation}
ℹ️ Local path prefix: http://{terminalIp}:{port}/terminal/v1/sync/{operation}

Charge

Single-step payment — authorization and capture in one operation. Standard flow for most retail merchants.

{
  "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 them. Use for hotels, gas stations, or open-tab scenarios where the final amount is unknown at card-present time.

Supported networks: Visa and Mastercard.

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

Capture

Collects funds reserved by a prior authorization.

transaction_reference must come from an authorization response.

Capture 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 — used in post-tip flows where the customer decides the gratuity after the initial charge.

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

Void

Cancels a transaction on the same business day, before the processor cutoff. The amount is never debited from the cardholder's account.

Wait at least 1 minute after the original transaction before calling void.

Cutoff in Chile: 23:59 local time.

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

Refund

Refunds a previously captured and settled transaction. Can be executed days after the original charge.

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

Abort

Immediately cancels a transaction currently in progress on the terminal.

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

No request body required — for Local mode, use GET /abort.

Transaction Search

Returns terminal transaction history sorted by date descending.

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

ℹ️ Local mode has two search endpoints: POST /transaction_search_online for online transactions and POST /transaction_search_local for offline/fallback transactions.

Amount object

All amount fields use CLP integers — no decimal places.

"amount": {
  "subtotal_iva0": 10000,
  "subtotal_iva": 0,
  "iva": 0,
  "extra_taxes": {
    "airport_tax": 0,
    "iac": 0,
    "ice": 0,
    "travel_agency": 0
  }
}

Authentication

Payment API requests are signed with HMAC-SHA256 — different from the Private-Merchant-Id used in Online Payments.

Include both headers on every request that has a body:

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 for requests with no body (e.g. abort in Local mode).

Base URLs

☁️ Cloud — Production

☁️ Cloud — UAT

🏠 Local Network

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

Available Endpoints

Charge (Cloud)

One-step payment via cloud.

Charge (Local)

One-step payment via local network.

Authorization (Cloud)

Pre-authorize via cloud.

Authorization (Local)

Pre-authorize via local network.

Capture (Cloud)

Capture reserved funds via cloud.

Capture (Local)

Capture reserved funds via local network.

Void (Cloud)

Cancel a same-day transaction via cloud.

Void (Local)

Cancel a same-day transaction via local network.

Refund (Cloud)

Refund a settled transaction via cloud.

Refund (Local)

Refund a settled transaction via local network.

Post-tip (Cloud)

Add gratuity to an authorized transaction via cloud.

Post-tip (Local)

Add gratuity to an authorized transaction via local network.

Re-authorization (Cloud)

Extend or increase a pre-auth via cloud.

Re-authorization (Local)

Extend or increase a pre-auth via local network.

Abort (Cloud)

Cancel an in-progress transaction via cloud.

Abort (Local)

Cancel an in-progress transaction via local network.

Transaction Search (Cloud)

Query terminal transaction history via cloud.

Transaction Search (Local)

Query online and offline transaction history via local network.

Got a suggestion on this documentation? Contact us.

Operations#

Charge#

Authorization (Pre-auth)#

Capture#

Re-authorization#

Post-tip#

Void#

Refund#

Abort#

Transaction Search#

Amount object#

Authentication#

Base URLs#

Available Endpoints#

Operations

Charge

Authorization (Pre-auth)

Capture

Re-authorization

Post-tip

Void

Refund

Abort

Transaction Search

Amount object

Authentication

Base URLs

Available Endpoints