API каси: платежі з вашого сайту
Ключ API, створення платежу, перевірка статусу, вебхук з підписом і приклад на PHP.
API каси - для магазину привілеїв чи будь-якого сайту: ваш сайт створює платіж, відправляє гравця на сторінку оплати, а після оплати отримує вебхук із підписом. Усі запити - JSON, адреса https://h0st.pro/api/cassa/…, заголовок Authorization: Bearer <ключ каси>.
1. Створити платіж
POST /api/cassa/payments
| Поле | Що це |
|---|---|
amount | сума в гривнях, яку хочете отримати (комісія - за налаштуванням каси) |
order_id | ваш номер замовлення (унікальний у касі; повторний запит повертає той самий платіж) |
payer | нік або Steam ID гравця (до 40 символів) |
description | що купують, напр. «VIP на 30 днів» (до 200) |
custom | будь-які ваші дані (об'єкт до 2 КБ) - повернуться у вебхуку |
return_url | куди повернути гравця після оплати |
Відповідь 201: {"payment": {"id", "order_id", "status", "amount", "fee", "net", "pay_url", …}}. Відправте гравця на pay_url.
curl -X POST https://h0st.pro/api/cassa/payments \
-H "Authorization: Bearer cassa_ВАШ_КЛЮЧ" -H "Content-Type: application/json" \
-d '{"amount": 100, "order_id": "vip-1001", "payer": "STEAM_0:1:123", "description": "VIP на 30 днів", "return_url": "https://site.com/thanks"}'
2. Статус платежу
GET /api/cassa/payments/{id} або GET /api/cassa/payments?order_id=…. Статуси: pending - очікує, paid - оплачено, failed, expired (24 години), refunded.
3. Вебхук
Коли платіж оплачено, ми робимо POST на адресу вебхука з вашої каси. Тіло - JSON: {"event": "payment.paid", "payment": {…}, "site": {…}}. Не дійшов (не 2xx) - повторюємо через 1, 5, 15 хвилин, 1, 6 і 24 години; у касі видно статус доставки й кнопку «надіслати ще раз».
Перевіряйте підпис: заголовок X-Cassa-Signature - це HMAC-SHA256 від рядка <X-Cassa-Timestamp>.<сире тіло> із секретом вебхука. Без перевірки будь-хто зможе «оплатити» собі VIP.
<?php // h0st-cassa.php на вашому сайті
$secret = 'СЕКРЕТ_ВЕБХУКА';
$body = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_CASSA_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_CASSA_SIGNATURE'] ?? '';
if (!hash_equals(hash_hmac('sha256', $ts . '.' . $body, $secret), $sig) || abs(time() - (int) $ts) > 300) {
http_response_code(400); exit('bad signature');
}
$data = json_decode($body, true);
if ($data['event'] === 'payment.paid') {
$p = $data['payment'];
// $p['order_id'], $p['payer'], $p['net'] (отримана сума), $p['custom']
// видайте привілей; платіж з тим самим id може прийти ще раз - перевіряйте, чи вже зараховано
}
http_response_code(200); echo 'ok';
Перевірити ключ
GET /api/cassa/me повертає назву каси, комісію й режим виведення (balance - на баланс h0st, mono - на ваш рахунок).