Accept payments with Kushki One

🚧 Early Release — Beta

This product is in early access. Parameters, response structures and behaviors may change without prior notice. Do not use this version in production without coordinating with the Kushki integrations team first.

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

Before you start

A Sunmi P3 or P2 SE terminal linked to your merchant account and running in semi-integrated mode.

Your Business-Code, provided by the integrations team.

Each device's terminalSerial. The integrations team hands it over during onboarding.

Your connection topology decided: Cloud, Local Network or Localhost.

How it works

The payloads and the headers are identical between topologies. The routes are not — three things change, and they are listed under the base URLs.

Topology	Base URL
Local Network (LAN / Wi-Fi)	`http://{TERMINAL_IP}:6868/terminal/v1` or `https://{TERMINAL_IP}:6869/terminal/v1`
Cloud (Internet) — UAT	`https://uat-cloudt.kushkipagos.com/terminal/v1/{terminalSerial}`
Cloud (Internet) — Production	`https://cloudt.kushkipagos.com/terminal/v1/{terminalSerial}`

What changes between Cloud and the local network, beyond the base URL:

Difference	Local Network	Cloud
`/abort` method	`GET`, in both modes	`POST`, sync only
Async abort	Available	Does not exist
Print routes	`/terminal/v1/print`	`/{terminalSerial}/sync/print`

Not sure which topology to use?

Read Integration topologies in Getting started before you continue.

Sync and async modes

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

Mode	Prefix	Behavior	Where the result arrives
Sync	`/sync/`	Holds the connection open until the acquirer answers	In the HTTP response
Async	`/async/`	Returns immediately with a `TERMINAL_ACKNOWLEDGED` acknowledgement. Never blocks	Webhook only

When to use async mode

A card-present payment depends on a person's interaction and frequently exceeds the 15 seconds most POS architectures tolerate. If your system cannot hold a connection open that long, use async mode and consume the events over webhook.

Available operations

Operation	Path	Sync	Async	What it does
Sale	`/charge`	✅	✅	Immediate charge: authorizes and captures in a single step
Authorization	`/authorization`	✅	✅	Reserves funds without capturing them
Capture	`/capture`	✅	✅	Charges the funds from an approved authorization
Re-authorization	`/re_authorization`	✅	✅	Extends the amount or the validity of an active authorization
Post-tip	`/pos_tip`	✅	✅	Adds a tip to an already-authorized transaction
Reversal	`/void`	✅	✅	Reverses a transaction: cancellation within the calendar day, refund after the cut-off
Abort	`/abort`	✅	✅	Cancels an operation in progress on the terminal
Online search	`/transaction_search_online`	✅	—	Queries transaction history at the acquirer
Local search	`/transaction_search_local`	✅	—	Queries the history stored on the terminal

/abort differs between topologies

On Local Network, /abort uses the GET method and is available in both modes. On Cloud it uses POST and only exists in sync mode.

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.

Persist this value

Store the transaction_reference in your database the moment you receive the response. Without it you cannot capture, re-authorize, void or refund that transaction.

Amount structure

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

Build the amount correctly

A badly built amount is the most common cause of incorrect charges. Read Amount format in Kushki ONE before your first integration.

Optional fields, by operation

These are the only optional fields, and each one belongs to specific operations. They behave the same in sync and async.

Field	Type	Applies to	What it does
`amount.tip`	integer	`/charge` and `/authorization`	Adds a tip. The tip can be set at pre-authorization time, not only when charging
`cashback_amount`	integer	`/charge`	Cash withdrawal on top of the purchase. Send `0` if it does not apply
`deferred` / `query_deferred`	object / boolean	`/charge`	Installments. The field and its shape change by country — see below
`omit_card`	boolean	`/capture`, `/re_authorization` and `/void`	With `true` the operation runs without asking for the card
`metadata`	object	`/charge`, `/authorization` and `/pos_tip`	Free-form traceability: `reference`, `customer_email`, `device`

On /pos_tip, amount.tip is not an optional field — it is the amount of the operation.

omit_card is what makes the hotel case work: extending or capturing a pre-authorization after the guest has left the desk.

Installments change by country

The two fields are mutually exclusive and never travel together:

Country	Field	Shape	Maximum
Mexico	`query_deferred`	Boolean. The terminal offers Meses Sin Intereses to the cardholder after reading the card; your POS does not choose the months	—
Chile	`deferred`	`months`, plus `credit_type: "03"` for cuotas comercio — a string, not a number	12 with `credit_type`, 48 without it
Colombia	`deferred`	`months` only. `credit_type` does not apply	48
Peru	`deferred`	`months` only. `credit_type` does not apply	2–48, every network

If a capability is not enabled for your terminal, the terminal ignores the field instead of rejecting the request — so a 200 does not prove the tip was applied. To have it enabled, write to soporte@kushkipagos.com.

Beta coverage

Only /charge has been exercised end-to-end with these fields, in sync and async. amount.tip on /authorization and omit_card on its six combinations are defined but not yet exercised — expect to be the first to run them.

Reading the HTTP status

On payment endpoints the status is always 200

Whatever happened, payment endpoints answer 200. The status confirms that the terminal processed your request — not that the operation succeeded. Always evaluate the response body. A POS that branches on response.ok treats a busy terminal, an expired PIN and a cardholder cancellation as successes.

The print endpoints are the exception: they return real codes, 404 when the job does not exist and 409 while the queue is busy.

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.

A re-authorization can be canceled

Once you cancel a re-authorization, the transaction accepts no further re-authorizations.

Authorization validity

Card type	Validity from authorization
Debit (Visa / Mastercard)	7 days
Credit (Visa / Mastercard)	28 days

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.

Reversal

There is a single reversal endpoint, /void, and the system decides what the operation becomes based on when you call it. The cut-off is 23:59 local time in every country: within the same calendar day the reversal is a cancellation; from midnight onwards it enters the refund cycle and takes business days.

Wait at least 1 minute

Wait at least 1 minute after the original transaction before reversing it, or it fails for no apparent reason.

The type returned by transaction search tells you what actually happened:

Type	What it means
`VOID`	You called `/void` on the same calendar day. Cancellation — the cardholder never sees the charge
`REFUND`	You called `/void` after the cut-off. It entered the refund cycle and takes business days
`REVERSE`	You did not ask for it. The platform generates it on its own when communication with the terminal fails

A REVERSE you never requested is not an error

Your POS can find a REVERSE in transaction search without having called anything. It is how the platform resolves a charge whose communication was cut mid-flight — the scenario where the POS charges, the link drops, and nobody knows whether the transaction landed.

Authentication

Kushki ONE uses one mechanism — hash + encryption — and it is the same in Cloud, on the local network and on localhost: Authorization: Basic <SHA512>, timestamp in seconds, and the body as the encrypted envelope {"data":"<iv_hex>:<cipher_hex>"}.

Every payload shown on this page is the plaintext you encrypt, not what travels on the wire. The full flow, the key derivation chain and the diagnostic tree are on Authentication and request encryption.

Local Network and Localhost: send the encrypted_http_communication header

In Local Network and Localhost, every request also carries the header encrypted_http_communication: true, in UAT and in production. Cloud does not require it. Details in Authentication and request encryption.

Do not confuse Business-Code with private_credential_id

The signing key is your Business-Code. The private_credential_id is a terminal configuration field and is not used to sign requests.

Set a long client timeout

Card-present flows wait on a person. Use at least 90 seconds on Cloud, where the relay adds latency on top of the terminal's own processing time, and 15 seconds on the local network. A 30-second timeout on Cloud produces phantom failures on charges that were in fact approved.

Direct sale example

A charge of 12000 minor units with no tax breakdown. What that represents depends on the country's decimals — check Amount format in Kushki ONE before your first integration.

JavaScript

Python

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.

Async services and webhooks

Integrate async mode: lifecycle states, event structure and the delivery retry policy.

Error catalog

Look up the error models, the codes by category and the corrective actions for every endpoint.

Accept payments with Kushki One

Requirements#

How it works#

Sync and async modes#

Available operations#

Key concepts#

client_transaction_id#

transaction_reference#

Amount structure#

Optional fields, by operation#

Installments change by country#

Reading the HTTP status#

Payment flows#

Direct sale#

Pre-authorization and capture#

Authorization validity#

Post-tip#

Reversal#

Authentication#

Direct sale example#

Best practices#

Requirements

How it works

Sync and async modes

Available operations

Key concepts

client_transaction_id

transaction_reference

Amount structure

Optional fields, by operation

Installments change by country

Reading the HTTP status

Payment flows

Direct sale

Pre-authorization and capture

Authorization validity

Post-tip

Reversal

Authentication

Direct sale example

Best practices