Payment

Payment operations let your POS trigger a card transaction on a terminal it cannot reach directly. Your server calls cloudt.kushkipagos.com, Kushki routes the command to the terminal identified by its serial number, and the cardholder interacts with the device.

Beta — Early Access

Kushki ONE Cloud is currently in Beta for Colombia 🇨🇴. Do not deploy to production without coordinating with the Kushki integration team.

Pick a variant first

Every payment operation ships twice, under two path prefixes. The choice is about where you receive the outcome, not about what the terminal does.

	Sync	Async
Prefix	`/sync/`	`/async/`
HTTP response	The full transaction result	A `TERMINAL_ACKNOWLEDGED` acknowledgement
Blocks?	Yes, until the acquirer answers	No
Outcome arrives	In the response	On your `events_webhook_url`
Operations	8	6

Async exists because card-present flows wait on a human and routinely exceed the ~15 second timeout budget of most POS architectures. If your stack can hold a request open for 90 seconds, sync is simpler. If it cannot, async is the only safe option.

Refund, abort and transaction search are sync-only.

Request shape

All operations share the same skeleton:

{
  "amount": {
    "subtotal_iva0": 10000,
    "subtotal_iva": 0,
    "iva": 0
  },
  "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af79"
}

Element	Rule
`amount`	Integers only. COP has no decimals — `10000` is $ 10.000
`client_transaction_id`	UUID v4. It is your idempotency key — reuse it on retries
`transaction_reference`	Required on capture, re-authorization, void and refund. Comes from `rawResponse.transaction_reference` of the original operation

There is no currency field — the terminal's DMS configuration decides it.

IVA

Colombia's VAT rate is 19%. Split the amount into its taxed and exempt parts and state the tax
explicitly — the terminal does not compute it for you:

Field	What goes in it
`subtotal_iva`	Net amount subject to IVA
`subtotal_iva0`	Amount exempt from IVA
`iva`	The IVA itself: `subtotal_iva × 0.19`

To charge 59.500 total:

"amount": { "subtotal_iva": 50000, "iva": 9500, "subtotal_iva0": 0 }

An IVA-exempt sale puts the whole amount in subtotal_iva0 and leaves the other two at 0. Either
way the three fields are required.

WARNING

Set your HTTP client timeout to at least 90 seconds on sync operations. The cloud relay adds latency on top of the terminal's own processing time.

See Cloud Services for authentication, the amount format in full, and the transaction lifecycle.

Folders

Sync

8 blocking operations. The result comes back in the HTTP response.

Async

6 non-blocking operations. The result arrives on your webhook.

Query the terminal's transaction history.

Got a suggestion on this documentation? Contact us.

Pick a variant first#

Request shape#

IVA#

Folders#

Pick a variant first

Request shape

IVA

Folders