# CHECKOUT.UZ API Documentation (for LLMs) > CHECKOUT.UZ is a unified payment gateway for Uzbekistan. This file is a > plain-text, complete reference of its REST API, written for LLMs and AI > agents that need to understand or integrate with it without executing > JavaScript or crawling a rendered web page. The human-friendly, interactive version of this documentation (with a live "Try it out" console, and cURL/JavaScript/PHP code samples) is at: https://checkout.uz/api-docs — also available in Russian, English and Tajik via the language switcher. ## Overview - API version: 1.3.0 - Style: REST, JSON request and response bodies - Base URL (production): https://checkout.uz/api/v1 - Base URL (backup): https://pre-view.checkout.uz/api/v1 - All endpoints below are called with POST and accept/return `application/json` (except where noted). - Monetary amounts are in UZS (Uzbek so'm) unless a response explicitly says otherwise (e.g. `get_balance`, which can also hold `usd`/`ton`). ## Authentication Every request must include your cash desk's ("kassa") API key as a Bearer token in the `Authorization` header: Authorization: Bearer YOUR_API_KEY - Get your API key from the dashboard: cash desk settings → API (https://checkout.uz/dashboard/shops). - The cash desk must be in `Faol` (Active) status — a pending or disabled cash desk's key will not authenticate, even if the key itself is correct. - If IP Whitelist is enabled for the cash desk, requests are only accepted from the whitelisted IP addresses. - Missing/invalid token → `401 Unauthorized`. - IP not whitelisted → `403 Forbidden`. ## Error format Errors are returned as JSON with an `error` field and an appropriate HTTP status code. Examples: 401 { "error": "Unauthorized: Invalid or missing Bearer token" } 403 { "error": "Access denied: Your IP (1.2.3.4) is not whitelisted" } 404 { "error": "Payment not found" } 400 { "error": "Invalid amount", "allowed": { "min": 1000, "max": 10000000, "currency": "UZS" } } ## Endpoints ### 1. POST /create_payment Create a new payment link (invoice). Request body (JSON): - `amount` (number, required) — payment amount in UZS. Must be between 1,000 and 10,000,000 inclusive. - `description` (string, optional) — free text shown to the payer. Defaults to a generic description if omitted. Example request: curl -X POST https://checkout.uz/api/v1/create_payment \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"amount": 50000, "description": "Order #12345"}' Example success response (200): { "status": "success", "payment": { "_id": 152, "_uuid": "550e8400-e29b-41d4-a716-446655440000", "_url": "https://checkout.uz/pay/550e8400-e29b-41d4-a716-446655440000", "_amount": 50000, "_status": "pending", "_pay_via": { "click": "https://checkout.uz/pay/550e8400-e29b-41d4-a716-446655440000/via/click", "payme": "https://checkout.uz/pay/550e8400-e29b-41d4-a716-446655440000/via/payme" }, "_lifteme": { "_second": 3600, "_hour": 1 } } } Notes: - `_url` is a hosted checkout page — redirect the payer there, or open it in an iframe/new tab. - `_pay_via` gives direct one-click links per payment method, and only includes methods enabled on the cash desk. It excludes bank-card flows (`card`/`vmcard`), which are only reachable through `_url`. - The invoice expires after `_lifteme` (default: 1 hour / 3600 seconds) if left unpaid. - Errors: `400` invalid amount, `401` unauthorized, `403` IP not whitelisted. ### 2. POST /status_payment Check the status of a payment by its numeric ID or UUID. Request body (JSON): - `id` (integer, optional) — the invoice's numeric ID. - `uuid` (string, optional) — the invoice's UUID (same value as `_uuid` from `create_payment`). - Exactly one of `id` or `uuid` must be supplied. Example request: curl -X POST https://checkout.uz/api/v1/status_payment \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"uuid": "550e8400-e29b-41d4-a716-446655440000"}' Example success response (200): { "status": "success", "data": { "id": 152, "amount": 50000, "status": "paid", "created_at": "2026-01-31 10:00:00", "paid_at": "2026-01-31 10:05:22" } } `status` is one of: `pending`, `paid` (an invoice may also be left unpaid and simply expire after its `_lifteme` window). Errors: `400` neither/both of id and uuid supplied with the wrong type, `404` payment not found (also returned if the invoice belongs to a different cash desk than the one that owns the API key used). ### 3. POST /get_balance Get the current balance of the authenticated cash desk, broken down by currency. Request body: none. Example request: curl -X POST https://checkout.uz/api/v1/get_balance \ -H "Authorization: Bearer YOUR_API_KEY" Example success response (200): { "status": "success", "balance": { "uzs": 2500000, "usd": 120, "ton": 15.5 } } ### 4. POST /get_history List the most recent transactions (invoices) for the authenticated cash desk, newest first. Request body (JSON): - `limit` (integer, optional, default `10`) — maximum number of records to return. Example request: curl -X POST https://checkout.uz/api/v1/get_history \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{"limit": 5}' Example success response (200): { "status": "success", "data": [ { "id": 152, "amount": 50000, "status": "paid", "created_at": "2026-01-31 10:00:00", "paid_at": "2026-01-31 10:05:22" }, { "id": 151, "amount": 120000, "status": "paid", "created_at": "2026-01-30 18:22:11", "paid_at": "2026-01-30 18:23:40" } ] } ### 5. POST /get_stats Get aggregate statistics for the authenticated cash desk. Request body: none. Example request: curl -X POST https://checkout.uz/api/v1/get_stats \ -H "Authorization: Bearer YOUR_API_KEY" Example success response (200): { "status": "success", "stats": { "total_orders": 450, "total_amount": 12500000.50 } } `total_orders` counts every invoice ever created for the cash desk (any status); `total_amount` sums only invoices whose `status` is `paid`. ## Webhooks (payment notifications) When a payment is confirmed, CHECKOUT.UZ sends an HTTP POST request with a JSON body to the `webhook_url` configured for the cash desk (dashboard → cash desk settings). This lets your server react in real time instead of polling `/status_payment`. - Method: POST, `Content-Type: application/json`. - Timeout: your endpoint has 15 seconds to respond (5 second connect timeout); the delivery is considered successful only if you return HTTP `200`. - Retries: delivery is best-effort and is not automatically retried on failure — reconcile periodically via `/status_payment` or `/get_history` if you need guaranteed consistency. - No cryptographic signature is currently attached to webhook requests. Re-verify the payment via `/status_payment` server-side before crediting anything critical, and keep your `webhook_url` private/unguessable. Example webhook payload: { "webhook_type": "version_1_1", "status": "success", "event": "payment_confirmed", "payment_system": "click", "shop_id": 42, "data": { "order_id": 152, "amount": 50000, "currency": "UZS", "status": "paid", "provider_details": { "...": "raw callback payload from the payment provider" }, "merchant_prepare": 998877, "perform_time": 1735689600000 }, "timestamp": 1735689600 } `payment_system` is one of: `click`, `payme`, `plum`, `vmcard` (bank card). The exact shape of `data` varies slightly per payment system, but `order_id`, `amount` and `status` are always present. ## Supported payment systems Depending on what's enabled per cash desk, payments can be accepted via: Click, Payme, Uzcard/Humo bank cards, and Plum. All amounts are currently processed in UZS. ## Limits - Minimum payment amount: 1,000 UZS - Maximum payment amount: 10,000,000 UZS per invoice - Unpaid invoices expire after 1 hour (3,600 seconds) by default ## Related pages - Interactive API docs with a live request console: https://checkout.uz/api-docs - Dashboard (create a cash desk, get an API key, configure webhook URL and IP whitelist): https://checkout.uz/dashboard - Sign up: https://checkout.uz/auth/register