Payment - Kushki Developer Portal

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 Perú 🇵🇪. 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, in céntimos. PEN and USD both have two decimals, so `10000` is S/ 100.00
`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

The payload has no currency field — the terminal's DMS configuration decides whether it is PEN or USD.

IGV

Peru's VAT is the IGV, 18%. The API field is still called iva — that name is shared across markets — but in Peru it carries the IGV:

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

To charge S/ 5.00 net plus IGV — S/ 5.90 total — send it in céntimos:

"amount": { "subtotal_iva": 500, "iva": 90, "subtotal_iva0": 0 }

An IGV-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.

Payment Cloud

Pick a variant first#

Request shape#

IGV#

Folders#

Pick a variant first

Request shape

IGV

Folders