Authorization — Pre-auth (Async) - Kushki Developer Portal

Same body as the sync variant plus events_webhook_url.

Returns 200 with a TERMINAL_ACKNOWLEDGED event as soon as the terminal accepts the payment intent. That acknowledgement is not the transaction result — the outcome, and every intermediate state, arrives as a POST to the events_webhook_url you supply. Omit the URL and the transaction still runs, but you never learn how it ended.

🚧 Beta — Early Access
This API is in early access. Endpoints, parameters, and response structures
may change without prior notice. Do not deploy to production without
coordinating with the Kushki integration team.

What you encrypt

The body you send is the encrypted envelope. This is the plaintext object you encrypt — the field contract, not what travels on the wire:

{
    "events_webhook_url": "https://api.negocio.co/webhook/terminal-events",
    "amount": {
        "iva": 0,
        "subtotal_iva": 0,
        "subtotal_iva0": 50000,
        "tip": 0,
        "extra_taxes": {
            "airport_tax": 0,
            "iac": 0,
            "ice": 0,
            "travel_agency": 0
        }
    },
    "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af30",
    "metadata": {
        "reference": "HOTEL-ROOM-302",
        "device": "SUNMI-P3"
    }
}

amount.tip is optional on charge and on authorization — the tip can be set at pre-authorization time. cashback_amount is optional on charge. On pos_tip the tip is not an optional field: it is the amount of the operation. Each one needs the matching capability enabled for your terminal; when it is not, the terminal ignores the field instead of rejecting the request.

See Authentication and request encryption for the derivation chain and the seven steps.

application/json

Accepted by the terminal. Returns a TERMINAL_ACKNOWLEDGED event immediately — this is not the transaction result. The outcome arrives via webhook.

Bodyapplication/json

curl --location 'https://api-uat.kushkipagos.com/terminal/v1/async/authorization' \ --header 'Authorization: Basic 9f2c4e1b7a63d8f05c2e9b41a7d3086fbe15c4d29a7e0b38f6c1d52a94e7b3c0' \ --header 'timestamp: 1748476800' \ --header 'encrypted_http_communication: true' \ --header 'Content-Type: application/json' \ --data '{ "data": "a3f14c7e9b02d85fbc1e46a9d370f28b:9e0d7f21c4a8b653e17d902fac48b5d6e83c1704a9f26db8" }'

{ "event_id": "c08211a1-344c-4f1c-850b-41e33fb08cca", "previous_status": "", "occurred_at": "2026-08-03T20:53:34.859Z", "status": "TERMINAL_ACKNOWLEDGED", "merchant_id": "20000000106033700000", "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af79", "terminal": { "serialNumber": "TJ54241P20911", "model": "P2SE-BPKT", "wifiMac": "", "room": "3.0.10" }, "operation": { "type": "charge", "amount": { "extraTaxes": { "airportTax": 0, "iac": 0, "ice": 0, "travelAgency": 0 }, "iva": 0, "subtotalIva": 0, "subtotalIva0": 12000 }, "clientTransactionId": "c5a3f3be-9d6f-4d39-8af5-58dbb589af79", "eventsWebHook": "https://api.negocio.co/webhook/terminal-events", "metadata": { "customerEmail": "user@example.com", "device": "SUNMI-P3", "reference": "ORD-20240317-001" } } }

Authorization — Pre-auth (Async)

🚧 Beta — Early Access

What you encrypt

Callbacks

transactionEvents

Request

Responses

Authorization — Pre-auth (Async)

🚧 Beta — Early Access#

What you encrypt#

Callbacks

transactionEvents

Request

Responses

🚧 Beta — Early Access

What you encrypt