Payment API Reference

Use separate credentials per surface. Send them only in headers, only over HTTPS, and never in query strings, logs, or browser bundles.

Merchant API Authorization: Bearer API_KEY

Used by /api/create/ and /api/getter/. One key per merchant; rotate by disabling the old row after clients switch.

Payment webhook X-Secret-Key: PAYMENT_WEBHOOK_SECRET

Used by /api/status/ for trusted payment events.

Cron trigger X-Cron-Key: CRON_SECRET

Used by /api/cron/ to expire invoices and run maintenance.

Telegram webhook X-Telegram-Bot-Api-Secret-Token: TELEGRAM_WEBHOOK_SECRET

Used by /telegram.php for Telegram Business updates.

All examples use https://payments.example.com. Browser cross-origin access is not enabled.

5 endpoints documented

{
  "status": "success",
  "message": "invoice_created",
  "data": {
    "order_id": "pay_3f9a1c0e7b2d4a58b6c1e0d94f7a2b13",
    "amount": 50137,
    "currency": "UZS",
    "card_number": "8600000000001234",
    "card_holder": "CARD HOLDER",
    "status": "pending",
    "created_at": "2026-10-25 09:00:00",
    "end_time": "2026-10-25 09:05:00",
    "wait_time": 5
  }
}

curl --fail-with-body --tlsv1.2 \
  -H 'Authorization: Bearer API_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"amount":50000}' \
  https://payments.example.com/api/create/

const response = await fetch("https://payments.example.com/api/create/", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYMENT_API_KEY}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ amount: 50000 })
});
if (!response.ok) throw new Error(`Payment API HTTP ${response.status}`);
const result = await response.json();
if (result.status !== "success") throw new Error(result.message);
console.log(result.data.order_id, result.data.amount);

import os, requests

response = requests.post(
    "https://payments.example.com/api/create/",
    headers={"Authorization": f"Bearer {os.environ['PAYMENT_API_KEY']}"},
    json={"amount": 50000},
    timeout=(3, 10),
)
response.raise_for_status()
result = response.json()
if result.get("status") != "success":
    raise RuntimeError(result.get("message", "payment API error"))
print(result["data"]["order_id"])

$curl = curl_init("https://payments.example.com/api/create/");
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode(["amount" => 50000], JSON_THROW_ON_ERROR),
    CURLOPT_HTTPHEADER => [
        "Authorization: Bearer " . getenv("PAYMENT_API_KEY"),
        "Content-Type: application/json",
    ],
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CONNECTTIMEOUT => 3,
    CURLOPT_TIMEOUT => 10,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
]);
$body = curl_exec($curl);
$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
curl_close($curl);
if ($body === false || $status < 200 || $status >= 300) {
    throw new RuntimeException("Payment API request failed");
}
$result = json_decode($body, true, 32, JSON_THROW_ON_ERROR);

{
  "status": "success",
  "message": "order_found",
  "data": {
    "order_id": "pay_3f9a1c0e7b2d4a58b6c1e0d94f7a2b13",
    "amount": 50137,
    "card_number": "8600000000001234",
    "status": "success",
    "created_at": "2026-10-25 09:00:00",
    "end_time": "2026-10-25 09:05:00",
    "currency": "UZS"
  }
}

curl --fail-with-body --tlsv1.2 \
  -H 'Authorization: Bearer API_KEY' \
  'https://payments.example.com/api/getter/?order_id=pay_ORDER_ID'

{
  "amount": 50000,
  "card_last_4": "1234",
  "event_id": "bank:transaction-123456",
  "occurred_at": 1792100000
}

{
  "status": "success",
  "message": "event_recorded",
  "data": {
    "status": "success",
    "order_id": "pay_3f9a1c0e7b2d4a58b6c1e0d94f7a2b13",
    "duplicate": false
  }
}

curl --fail-with-body --tlsv1.2 \
  -H 'X-Cron-Key: CRON_SECRET' \
  -X POST \
  https://payments.example.com/api/cron/

curl --fail-with-body --tlsv1.2 \
  -H 'X-Telegram-Bot-Api-Secret-Token: TELEGRAM_WEBHOOK_SECRET' \
  -H 'Content-Type: application/json' \
  --data @update.json \
  https://payments.example.com/telegram.php

Callback URLs must use operator-allowlisted HTTPS hostnames on port 443 with publicly routable IPv4 addresses. The checked DNS result is pinned for the connection; redirects, proxies, and private or reserved addresses are rejected.

Verify the raw request body before parsing JSON, compare with a constant-time function, and reject timestamps outside a short tolerance.

import hmac, hashlib, time

def verify_callback(raw_body, timestamp, signature, secret):
    if abs(time.time() - int(timestamp)) > 300:
        return False
    expected = hmac.new(secret, (timestamp + ".").encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest("sha256=" + expected, signature)

• 200 success / not_foundBoth matched and unmatched payment events return HTTP 200 when accepted. Inspect data.status.
• 409 conflictReusing an event ID with a different amount, card suffix, or timestamp.
• 400 validationInvalid JSON, missing fields, bad timestamp window, or unsupported amount.
• 401 authMissing or invalid credential header.
• 413 large bodyJSON request body exceeds 64 KiB.
• 415 media typeUnsupported content type.
• 404 not foundUnknown endpoint, or order_not_found when the order does not exist or belongs to another merchant.
• 405 methodWrong HTTP method. The Allow header names the accepted one.
• 429 rate limitedToo many requests from your IP. Back off, then continue.
• 503 high_load / no_active_cardsTemporary overload or no card available. Retry after Retry-After seconds; reuse the same event_id for payment events.
• 500 server errorinternal_server_error carries no details. Retry with backoff and contact the operator if it persists.

• A duplicate event returns the recorded outcome with duplicate: true.
• A duplicate never searches for another invoice.
• Errors always look like {"status":"error","message":"…"}; branch on the HTTP status and message, never on free text.
• Never trust the top-level HTTP success alone as proof of settlement; inspect data.status.

1. 01 Transport

   HTTPS only. No credentials in query strings, logs, or browser bundles.

2. 02 Amounts

   Whole UZS integers only. Range and uniqueness constraints are enforced in the database.

3. 03 Idempotency

   Stable event IDs, conflicts on mismatched reuse, duplicates never re-match an invoice.

4. 04 Callbacks

   Exact host allowlisting, DNS pinning, no redirects, no proxies, TLS verification.

5. 05 Ingestion

   Telegram allowlists for senders and business connections. Forwards and edits are rejected.

6. 06 Secrets

   Loaded from the environment or .env. Never printed, logged, or returned.