Release notes
1.
2.
3.
Latest
1.1.0 - 2026-08-05
⚡ Asynchronous payment services
/async/ prefix, in both the Local Network and Cloud topologies.charge, authorization, capture, re_authorization, pos_tip and void. Local Network also exposes an async abort.status: TERMINAL_ACKNOWLEDGED and previous_status: "", returned without waiting for the acquirer.WARNING
🔔 Transaction webhooks with a seven-state lifecycle
events_webhook_url in the request body.TERMINAL_ACKNOWLEDGED, TERMINAL_CANCELED, CARD_PRESENTED, TERMINAL_REJECTED, APPROVAL_REQUESTED, DECLINED and APPROVAL. Five originate in the terminal; only APPROVAL and DECLINED come from the acquirer.TransactionEvent envelope serves both the async acknowledgement and every webhook delivery — write one deserializer for both.failure_reason carries type, code and message on TERMINAL_REJECTED and DECLINED.reading_type reports how the card was read: CHIP, CONTACTLESS or MAGNETIC_STRIPE.min(60s, 2s × 2^attempt) + random(0..2s) — stopping after 10 attempts or 15 minutes. If the terminal loses connectivity it queues events persistently and replays them, preserving per-transaction order.WARNING
event_id and correlate by client_transaction_id. Use previous_status to detect missing or out-of-order events.DANGER
APPROVAL_REQUESTED is the point of no return. Once the transaction reaches the acquirer it can no longer be aborted. Wait for APPROVAL or DECLINED, then reverse it with /void.📘 Transaction Examples guide
💰 Amount format documented for PEN
subtotal_iva0, subtotal_iva, iva, tip, cashback_amount and every member of extra_taxes are now declared as integer / int64 instead of floating-point numbers.WARNING
12000 is 120.00 PEN, not 12.000. The currency is configured on the terminal, so the same integer means different money on a terminal provisioned for another market.WARNING
12000.0) while requests take integers. Do not reuse an amount from an event to build a new request.🧾 Optional fields on charge and re-authorization
charge operation now documents three optional fields, and async re_authorization documents one.amount.tip — tip amount added to the total.cashback_amount — cash withdrawal on top of the purchase.query_deferred — when true, the terminal prompts the cardholder for installment options.omit_card — on re_authorization, skips card presentation for the operation.INFO
CONFIGURATION error (CONF-4001 tip, CONF-4002 cashback) — see the Error Catalog.🔍 Lifecycle status filter in local transaction search
filters.status field, replacing the previous transaction_type filter.🔑 Authentication headers documented as required
Authorization and timestamp are now declared as required headers on every operation of the Payment and Print APIs, in both topologies. Previously only the path parameters were documented.Authorization — HMAC-SHA256 signature of the raw request body, Base64-encoded.timestamp — Unix timestamp in milliseconds.🔐 Corrected the HMAC signing key
Private-Credential-Id. The correct signing key is the Business-Code.DANGER
private_credential_id is a terminal configuration field and is never used to sign requests. Signing with it returns AUTH-001 on every call.🖨️ Corrected the Print API Cloud paths
| Documented before | Correct path |
|---|---|
POST /terminal/v1/{terminalSerial}/sync/print/job | POST /terminal/v1/{terminalSerial}/sync/print |
POST /terminal/v1/{terminalSerial}/sync/print/job_status | POST /terminal/v1/{terminalSerial}/sync/print_job |
🖨️ Corrected how the print job status is queried in Cloud
print_job_id as a query parameter. It is sent in the request body.{
"print_job_id": "RECEIPT-20240317-001"
}INFO
GET /terminal/v1/print_job?print_job_id={id}, with the identifier in the URL. The asymmetry between topologies is intentional — see Get Print Job Status — Local.Previous release notes
1.0.0 - 2026-04-29
🎉 Kushki ONE Connect — initial release
charge, authorization, capture, re_authorization, pos_tip, void, abort and transaction search.Full control over the terminal's built-in thermal printer through a
commands array supporting text, columns, dividers, feeds, spacing, cut, images, QR codes and barcodes — with an asynchronous webhook reporting the final job status.Local Network (LAN / Wi-Fi) for direct HTTP to the terminal's IP, and Cloud (Internet) routed through Kushki's servers using the terminal serial. The request and response structures are identical in both — only the base URL changes.
A single structured JSON response for every failure, classified by
type into PARAMETER, TERMINAL, AUTHENTICATION, NOT_FOUND, ACQUIRER, INTERNAL, CONFIGURATION, TERMINAL-PRINTER and MANUFACTURER, with per-category code catalogs. See the Error Catalog.Got a suggestion on this documentation? Contact us.
Modified at 2026-09-09 18:27:55