Accept payments with Kushki One

March 31, 2026

Payments with SmartPOS terminal

The Payment API allows you to process in-person card payments from your checkout system to a Kushki ONE terminal (Sunmi P3, Sunmi P2 SE) in Semi-Integrated mode. The terminal manages all interaction with the customer and the EMV chip — your system only sends the amount and receives the result.

How it works

All endpoints share the same request and response structure regardless of how your POS connects to the terminal. The only thing that varies between topologies is the base URL:

Available Endpoints

Payment flows

Direct charge

The most common flow for retail merchants. The terminal activates the card reader and blocks until the customer completes the interaction and the acquirer responds.

POST /charge  →  200 OK (approved: true)

Pre-authorization and capture

Ideal for hotels, gas stations, and open-tab restaurants, where the final amount is not known at the time of customer interaction.

POST /authorization  →  saves transaction_reference
        ↓  (days later)
POST /capture  →  using the saved transaction_reference

Validity of pre-authorizations

Capture can be up to 110% of the total authorized amount (authorization + re-authorizations). Only one capture is allowed per authorization cycle.

Key concepts

client_transaction_id

UUID v4 identifier generated by your checkout system. It acts as an idempotency key: if the terminal has already processed that ID, it detects the duplicate and prevents double charging. Generate a unique one per attempt and reuse it only if you are retrying exactly the same operation.

transaction_reference

Identifier generated by Kushki and returned in the response of each approved transaction. It is the link between operations of the same lifecycle. Persist this value in your system — without it, you cannot capture, re-authorize, void, or refund.

Amount Structure

All endpoints that involve an amount use the same amount object.

Authentication

Include these headers in every request:

Voids and refunds

Endpoint reference

Charge — Direct charge

POST /terminal/v1/sync/charge

Authorization and capture in a single operation. The terminal activates the card reader upon receiving the request and blocks until the customer completes the interaction. Use it as the standard flow for most retail merchants.

See full reference →

Authorization — Pre-authorization

POST /terminal/v1/sync/authorization

Reserves funds in the cardholder’s account without capturing them. Use this flow when the final amount is not known at the time of customer interaction: hotels, gas stations, open-tab restaurants.

See full reference →

Capture — Capture

POST /terminal/v1/sync/capture

Charges the funds reserved by a previous authorization. Requires the transaction_reference returned in the /authorization response. The amount to capture can be equal to or less than the authorized amount, up to a maximum of 110% of the total (authorization + re-authorizations).

See full reference →

Re-authorization — Re-authorization

POST /terminal/v1/sync/re_authorization

Extends the reserved amount or the validity of an active pre-authorization before capture. It can be executed multiple times on the same base authorization. Send subtotal_iva0: 0 to extend only the validity without modifying the amount.

See full reference →

Post-tip — Post-tip

POST /terminal/v1/sync/pos_tip

Adds a tip to a transaction that has already been authorized. Use it in flows where the customer decides the tip amount after the initial charge. Send the tip amount in amount.tip.

See full reference →

Void — Void

POST /terminal/v1/sync/void

Cancels a transaction on the same day before the processor’s cutoff. The amount is never debited from the customer’s account. Wait at least 1 minute after the original transaction before executing a void.

See full reference →

Refund — Refund

POST /terminal/v1/sync/refund

Refunds an already captured and settled transaction. It can be executed days after the original charge. Requires the transaction_reference from the original charge or capture response.

See full reference →

Abort — Cancel active transaction

GET /terminal/v1/sync/abort

Immediately cancels any transaction in progress on the terminal. Does not require a request body. Call it only while a transaction is active — after it has completed (approved or declined), it returns 409 Conflict.

See full reference →

Transaction Search — History Query

Kushki ONE provides two search variants depending on the data source:

POST /terminal/v1/sync/transaction_search_online

Queries transaction history directly from the acquirer (Kushki). Returns the most complete and up-to-date data. Requires internet connectivity. Results are paginated and can be filtered by card, date range, or transaction type.

View full reference →

POST /terminal/v1/sync/transaction_search_local

Queries transaction history stored locally on the terminal. Useful for offline reconciliation or when the acquirer backend is unavailable. Does not support transaction_type as a filter.

View full reference →

Best practices

• Generate a unique client_transaction_id per attempt. Reuse it only in retries of the same logical operation.
• Persist transaction_reference in your database immediately upon receiving the authorization response.
• Verify that the amount fields sum correctly before sending the request.
• Log the sent client_transaction_id and the received HTTP code for each operation to facilitate reconciliation and support.
• Use abort only while a transaction is active on the terminal — calling it after it has completed returns 409 Conflict.

Consult the error models, codes, and recommended corrective actions for all Payment API endpoints in the Kushki ONE Error Catalog.