API hujjati — TolovGo

01Ulanish

4 qadam

Kassa oching. tolovgo.uz kabinetida «Kassa yaratish». Kassa admin tasdiqlagach faollashadi.
API kalitni oling. Kassa sahifasida «API kalit». Kalitga IP cheklovi qo'yish mumkin.
To'lov yarating. POST /create → javobdagi pay_url'ni mijozga bering.
Callback'ni qabul qiling. status=paid kelsa, imzoni tekshirib buyurtmani yoping.

Har so'rovda X-Api-Key sarlavhasi bo'lishi shart. Kalitga IP cheklovi qo'yilgan bo'lsa, boshqa IP'dan so'rov rad etiladi.

02Yo'llar

https://pay.tolovgo.uz/api ga nisbatan

Metod	Yo'l	Vazifasi
POST	/create	To'lov yaratish. Callback — GET, faqat to'langanda.
GET	/status/{order_id}	To'lov holati. `order_id` yoki `order_hash` beriladi.
POST	/v1/orders	To'lov yaratish, v1. Callback — JSON POST: `order.paid`, `order.expired`, `order.cancelled`, `order.refunded`.
GET	/v1/orders/{id}	To'lov holati, v1.

03POST /create

Maydonlar, so'rov va javob

Maydon	Tur	Izoh
amount	integer	Majburiy. So'mda, 1 000 — 99 999 999.
note	string	Izoh, 500 belgigacha. Callback'da qaytadi.
callback_url	url	To'lov bo'lganda chaqiriladi. Ochiq internet manzili bo'lishi kerak. Berilmasa — kassa sozlamasidagi manzil.
return_url	url	To'lovdan keyin mijoz qaytadigan sahifa.

v1 qo'shimcha maydonlari: external_id (64), description (500), payer.telegram_id, payer.username, payer.name.

So'rov

curl -X POST https://pay.tolovgo.uz/api/create \
  -H "X-Api-Key: SIZNING_KALIT" \
  -d amount=25000 \
  -d note="Buyurtma #1042" \
  -d callback_url=https://sayt.uz/tolovgo-callback

Javob · 201

{
  "ok": true,
  "status": "pending",
  "order_id": 1042,
  "amount": 25000,
  "pay_url": "https://pay.tolovgo.uz/pay/…",
  "providers": { /* click, payme, paynet — to'g'ridan-to'g'ri havolalar */ }
}

04Holatlar

To'lov hayoti

pending · paid · expired · cancelled · refunded

To'lanmagan havola 1 soatdan keyin expired bo'ladi. Callback kelgach ham, buyurtmani yopishdan oldin holatni GET /status/{order_id} bilan tasdiqlab olish tavsiya etiladi.

05Callback imzosi

Xabar TolovGo'dan kelganini tekshirish

Har callback'da uchta sarlavha keladi:

X-Rox-Event — hodisa, masalan order.paid;
X-Rox-Timestamp — Unix vaqt, soniyada;
X-Rox-Signature — sha256= + HMAC-SHA256(timestamp.body, kassa webhook siri).

body — POST'da JSON tanasi; GET'da faqat status, order_id, order_hash, amount, note shu tartibda. URL'ingizdagi boshqa parametrlar imzoga kirmaydi. Callback bir necha marta kelishi mumkin — ishlovchi takroriy so'rovni qayta bajarmasin.

// callback.php — imzoni tekshirish
$secret = 'KASSA_WEBHOOK_SECRET';
$ts  = $_SERVER['HTTP_X_ROX_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_ROX_SIGNATURE'] ?? '';

// GET callback: faqat shu 5 parametr, shu tartibda
$keys = ['status', 'order_id', 'order_hash', 'amount', 'note'];
$body = http_build_query(array_intersect_key(array_merge(array_flip($keys), $_GET), array_flip($keys)));
// v1 (POST): $body = file_get_contents('php://input');

$ok = hash_equals('sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret), $sig)
   && abs(time() - (int) $ts) < 300;

Imzo siri kassa sahifasida, «Webhook» bo'limida.

06Xatolar

HTTP kodlari

HTTP	Kod	Sabab
401	missing_credentials	X-Api-Key yuborilmagan
401	invalid_credentials	Kalit noto'g'ri
401	key_revoked	Kalit bekor qilingan
401	ip_not_allowed	Bu IP manzilga ruxsat yo'q
403	merchant_inactive	Kassa faol emas
422	—	Maydon noto'g'ri: `{"ok": false, "error": "…"}`
429	—	Daqiqasiga 120 so'rovdan oshdi

07Pul

Qayerga tushadi

To'lov — xizmat haqi (6%) ushlanib, kassa balansiga tushadi.
Yechish — kabinet orqali kartaga. Shartlari: Foydalanish shartlari, 5-bo'lim.
Qaytarish — v1 kassalarga order.refunded hodisasi keladi.