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

Abort and transaction search are sync-only — in Cloud there is no /async/abort.

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, new for every operation. It is your idempotency key — reuse it only when retrying that same operation
`transaction_reference`	Required on capture, re-authorization and void. Comes from `rawResponse.transaction_reference` of the original operation

WARNING

client_transaction_id and transaction_reference are not interchangeable. The first identifies this call; the second points at the transaction you are acting on. Passing the original transaction's id as client_transaction_id breaks idempotency.

The payload has no currency field — the terminal resolves the currency from its own configuration, and the integration team confirms which one your terminal uses during onboarding.

The optional fields (amount.tip, cashback_amount, deferred, omit_card, metadata) and which operation each one belongs to are listed in Cloud Services.

Note that the body you actually send is the encrypted envelope {"data":"<iv_hex>:<cipher_hex>"}. The payloads shown here and on the endpoint pages are the plaintext you encrypt.

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.

Reversing a transaction

There is a single reversal endpoint, /void, in both variants. What the operation becomes depends on when you call it: within the same calendar day as the original transaction it is a cancellation; from midnight onwards it enters the refund cycle and takes business days. Wait at least 1 minute after the original transaction before reversing it.

Transaction search reports which one happened, as VOID, REFUND or REVERSE — the last of these being one the platform generates on its own when communication with the terminal fails. See Cloud Services for the full table.

WARNING

On payment endpoints the HTTP status is always 200, whatever the outcome. Always evaluate the response body.

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

Folders

Sync

7 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#

Reversing a transaction#

Folders#

Pick a variant first

Request shape

IGV

Reversing a transaction

Folders