Accept payments with Kushki One

August 04, 2026

The Payment API lets you process card-present payments from your POS system to a Kushki ONE terminal running in semi-integrated mode. The terminal handles the entire cardholder interaction and the EMV chip: your system sends the amount and receives the result.

Requirements

How it works

Every endpoint shares the same request and response structure, no matter how you connect your POS to the terminal. The only thing that changes between topologies is the base URL.

Sync and async modes

Every operation that requires terminal interaction exists in two variants, under separate path prefixes.

Available operations

Key concepts

client_transaction_id

A UUID v4 identifier that your POS system generates. It works as an idempotency key: if the terminal already processed that identifier, it detects the duplicate and prevents a double charge.

Generate a new one for every sale. Reuse it only when you are retrying the exact same operation after a network failure.

transaction_reference

An identifier that Kushki generates and returns in the response of every approved transaction, inside rawResponse. It is the link between operations in the same lifecycle.

Amount structure

The amount object is sent in the currency’s minor units, as an integer. The number of decimals depends on the country.

Optional sale fields

These fields apply to /charge. The terminal handles the cardholder prompts and ignores the field when the capability is not enabled in the DMS.

On /re_authorization you also have omit_card: with true, the operation runs without asking for the card.

Payment flows

Direct sale

The most common retail flow. The terminal activates the reader when it receives the request and waits for the cardholder to complete the interaction.

POST /sync/charge  →  200 OK (approved: true)

Pre-authorization and capture

Use this when the final amount is unknown at the time of the interaction: hotels, fuel stations, open-tab restaurants.

POST /sync/authorization  →  store transaction_reference
        ↓  (hours or days later)
POST /sync/capture  →  with the stored transaction_reference

You can insert /re_authorization to raise the reserved amount or extend the window before capturing. Send subtotal_iva0: 0 to extend the validity only.

Authorization validity

The capture can reach up to 110% of the total authorized, adding the authorization and every non-canceled re-authorization. Only one capture is allowed per cycle.

Post-tip

Adds a tip to an already-authorized transaction. Use it when the cardholder decides the amount after the initial charge. Send the value in amount.tip alongside the original transaction_reference.

Void and refund

Authentication

Include these headers with every request:

Direct sale example

A 120.00 COP charge with no tax breakdown.

const payload = {
  amount: {
    iva: 0, subtotal_iva: 0, subtotal_iva0: 12000,
    extra_taxes: { airport_tax: 0, iac: 0, ice: 0, travel_agency: 0 },
  },
  client_transaction_id: crypto.randomUUID(),
};

const res = await fetch(`${BASE_URL}/sync/charge`, {
  method: "POST",
  headers: buildHeaders(payload),
  body: JSON.stringify(payload),
});
const data = await res.json();
console.log(data.approved, data.rawResponse.transaction_reference);

import uuid, requests

payload = {
    "amount": {
        "iva": 0, "subtotal_iva": 0, "subtotal_iva0": 12000,
        "extra_taxes": {"airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0},
    },
    "client_transaction_id": str(uuid.uuid4()),
}

res = requests.post(f"{BASE_URL}/sync/charge",
                    headers=build_headers(payload), json=payload)
data = res.json()
print(data["approved"], data["rawResponse"]["transaction_reference"])

Best practices

• Generate a unique client_transaction_id per sale and reuse it only when retrying the same operation.
• Persist the transaction_reference as soon as you receive the authorization or charge response.
• Check that the amount fields add up to the expected total before you send the request.
• Log the client_transaction_id and the HTTP code of every operation to make reconciliation and support easier.
• Call /abort only while a transaction is active on the terminal. Calling it afterwards returns 409 Conflict.
• Sign exactly the same bytes you send: serialize once, sign that string and send that same string.