Документация API

01Подключение

4 шага

Откройте кассу. В панели tolovgo.uz — «Создать кассу». Касса станет активной после одобрения администратором.
Получите API-ключ. На странице кассы — «API-ключ». Для ключа можно задать ограничение по IP.
Создайте платёж. POST /create → отдайте клиенту pay_url из ответа.
Примите callback. Когда придёт status=paid, проверьте подпись и закройте заказ.

Каждый запрос должен содержать заголовок X-Api-Key. Если для ключа задано ограничение по IP, запросы с других IP отклоняются.

02Методы

относительно https://pay.tolovgo.uz/api

Метод	Путь	Назначение
POST	/create	Создание платежа. Callback — GET, только после оплаты.
GET	/status/{order_id}	Статус платежа. Передаётся `order_id` или `order_hash`.
POST	/v1/orders	Создание платежа, v1. Callback — JSON POST: `order.paid`, `order.expired`, `order.cancelled`, `order.refunded`.
GET	/v1/orders/{id}	Статус платежа, v1.

03POST /create

Поля, запрос и ответ

Поле	Тип	Описание
amount	integer	Обязательно. В сумах, 1 000 — 99 999 999.
note	string	Комментарий, до 500 символов. Возвращается в callback.
callback_url	url	Вызывается после оплаты. Должен быть публичным адресом. Если не указан — адрес из настроек кассы.
return_url	url	Страница, куда клиент вернётся после оплаты.

Дополнительные поля v1: external_id (64), description (500), payer.telegram_id, payer.username, payer.name.

Запрос

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

Ответ · 201

{
  "ok": true,
  "status": "pending",
  "order_id": 1042,
  "amount": 25000,
  "pay_url": "https://pay.tolovgo.uz/pay/…",
  "providers": { /* click, payme, paynet — прямые ссылки */ }
}

04Статусы

Жизненный цикл платежа

pending · paid · expired · cancelled · refunded

Неоплаченная ссылка через 1 час переходит в expired. Даже после callback рекомендуется подтвердить статус через GET /status/{order_id} перед закрытием заказа.

05Подпись callback

Как убедиться, что уведомление пришло от TolovGo

В каждом callback приходят три заголовка:

X-Rox-Event — событие, например order.paid;
X-Rox-Timestamp — время Unix в секундах;
X-Rox-Signature — sha256= + HMAC-SHA256(timestamp.body, секрет webhook кассы).

body — для POST тело JSON; для GET только status, order_id, order_hash, amount, note в этом порядке. Другие параметры вашего URL в подпись не входят. Callback может прийти несколько раз — обработчик не должен выполнять повторный запрос дважды.

// callback.php — проверка подписи
$secret = 'KASSA_WEBHOOK_SECRET';
$ts  = $_SERVER['HTTP_X_ROX_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_ROX_SIGNATURE'] ?? '';

// GET callback: только эти 5 параметров, в этом порядке
$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;

Секрет подписи — на странице кассы, в разделе «Webhook».

06Ошибки

Коды HTTP

HTTP	Код	Причина
401	missing_credentials	Не передан X-Api-Key
401	invalid_credentials	Неверный ключ
401	key_revoked	Ключ отозван
401	ip_not_allowed	Доступ с этого IP запрещён
403	merchant_inactive	Касса не активна
422	—	Неверное поле: `{"ok": false, "error": "…"}`
429	—	Превышен лимит 120 запросов в минуту

07Деньги

Куда поступают

Платёж — за вычетом комиссии сервиса (6%) зачисляется на баланс кассы.
Вывод — на карту через панель. Условия: Условия использования, раздел 5.
Возврат — кассы v1 получают событие order.refunded.