Authorization (Pre-auth)

Reserves funds without capturing them. Use when the final amount is
unknown at card-present time: hotels, gas stations, open-tab restaurants.

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

Supported networks: Visa and Mastercard (debit and credit).

Card type	Validity
Debit	7 days
Credit	28 days

Save rawResponse.transaction_reference — required for capture,
re_authorization, and void.

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:

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

curl --location '/terminal/v1/sync/authorization' \ --header 'Authorization: Basic 9f2c4e1b7a63d8f05c2e9b41a7d3086fbe15c4d29a7e0b38f6c1d52a94e7b3c0' \ --header 'timestamp: 1748476800' \ --header 'encrypted_http_communication: true' \ --header 'Content-Type: application/json' \ --data '{ "data": "a3f14c7e9b02d85fbc1e46a9d370f28b:9e0d7f21c4a8b653e17d902fac48b5d6e83c1704a9f26db8" }'

{ "hostRespond": true, "approved": true, "responseCode": "000", "authCode": "123456", "issuerAuthenticationData": "663cddbc3ec72e76", "issuerScript1": "9f180441424344860d841e00000872d7d06b30fdb0df860d841e00000895609d17caff5d43860d841e000008d3b5782ce1f80b6a860d841e00000832c88ba879f5d0b4860d841e000008db4922e8ba157ae9860d841e000008ff98d27978f0577c860d841e000008a859a01deca6f384", "issuerScript2": "9f180430303031860e04da9f58090335454008649d370c", "message": "Approved or completed successfully.", "rawResponse": { "additional_amounts": { "account_type": "", "amount": 0, "amount_type": "", "card_type": "", "currency_code": "" }, "authorized_amount": 120, "card_type": "credit", "cvm_type": "pin", "franchise": "VISA", "kushki_response": { "code": "000", "message": "Approved or completed successfully." }, "transaction_reference": "983a7480-6d97-41c3-bdd8-d3cde6685c17", "transaction_status": "APPROVAL", "transaction_type": "preAuth", "ticket_number": "110993659310263283", "F11": "147009", "message_fields": { "F38": "123456", "F39": "00", "F55": "9108663cddbc3ec72e7671709f180441424344860d841e00000872d7d06b30fdb0df860d841e00000895609d17caff5d43860d841e000008d3b5782ce1f80b6a860d841e00000832c88ba879f5d0b4860d841e000008db4922e8ba157ae9860d841e000008ff98d27978f0577c860d841e000008a859a01deca6f38472179f180430303031860e04da9f58090335454008649d370c" } }, "cardData": { "pan": "**** **** **** 0043", "cardHolderName": "554154205553412F546573742043617264203032", "entryMode": "ICC", "cvm": "pin", "aid": "A0000000031010", "bin": "453985", "arqc": "960E7A7DE8F6E874", "tc": "" }, "timestamp": 1772636209320, "request": { "amount": { "currency": "PEN", "iva": 0, "subtotal_iva": 0, "subtotal_iva0": 12000, "extra_taxes": { "airport_tax": 0, "iac": 0, "ice": 0, "travel_agency": 0 } }, "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af69", "show_decimal_places": true, "is_async": false, "events_webhook_url": "", "transaction_mode": "Authorization" }, "needReversal": false }

🚧 Beta — Early Access

What you encrypt

Request

Responses

Authorization (Pre-auth)

🚧 Beta — Early Access#

What you encrypt#

Request

Responses

🚧 Beta — Early Access

What you encrypt