Новинка! API для Telegram ботів: Документація Telegram API
Swagger API Документація
Для зручної роботи з API ми надали інтерактивну Swagger документацію, яка дозволяє переглядати всі доступні API endpoints, бачити параметри запитів та приклади відповідей, тестувати API прямо в браузері та імпортувати специфікацію в Postman та інші інструменти.
Swagger документація:
https://test.aifo.pro/docs/swaggerSwagger документація містить всю інформацію про API endpoints, які описані нижче, але в більш зручному та інтерактивному форматі. Рекомендуємо використовувати Swagger для розробки та тестування інтеграцій.
JSON специфікація доступна за адресою: https://test.aifo.pro/docs/swagger/spec
Створення платежу
Для ініціалізації платежу через єдину форму оплати достатньо направити користувача за спеціальною URL-адресою, а також передати ряд обов'язкових параметрів.
URL форми оплати:
https://test.aifo.pro/pay/?shop_id=ID&pay_id=ID_платежу&amount=Сума&sign=ПідписФорма оплати містить усі необхідні дані для проведення платежу. Передається методом GET/POST на адресу.
| Параметр | Примітка | Тип |
|---|---|---|
| shop_id | ID каси, можна отримати в налаштуваннях проєкту. | Обов'язковий. |
| amount | Сума платежу. | Обов'язковий. |
| pay_id | Номер рахунку. Може бути ваш ID замовлення (виджет або пряме посилання) або системний invoice_id (посилання з API). Система спочатку шукає інвойс за вашим id (invoice_uid), потім за invoice_id. | Обов'язковий. |
| sign | Підпис платежу. | Обов'язковий. |
| desc | Коментар до платежу. | Необов'язковий. |
- Ваш ID замовлення — для посилань з віджету в налаштуваннях каси або згенерованих вручну. Підпис: hash(shop_id:amount:secret:ваш_id). Система спочатку шукає інвойс за вашим id.
- Системний invoice_id — для посилань з API (payment_url після створення через API). Якщо за вашим id інвойс не знайдено і pay_id — число, використовується пошук за invoice_id. Рекомендується використовувати payment_url з відповіді API, не формувати посилання вручну.
Підпис для створення платежу формується шляхом обчислення SHA256 || SHA1 || SHA512 || SHA384 || RIPEMD160-хешу. Рекомендується SHA256.
Увага: MD5 застарілий і небезпечний. Використовуйте SHA256 або інші безпечні алгоритми.
Важливо: Для генерації підпису використовуйте секретний ключ (kassa_secretkey), а не публічний ключ. Секретний ключ доступний тільки вам і не повинен публікуватися.
Приклад коду на PHP (підпис):
$sign = hash('sha256', "ID_магазину:Сума:секретний_ключ:Номер_рахунку");
$sign = hash('sha1', "ID_магазину:Сума:секретний_ключ:Номер_рахунку");
Перевірка IP
Рекомендуємо перевіряти IP сервера, що надсилає інформацію. Наші IP — 77.83.102.155
Приклад коду на PHP:
function getIP() {
if (isset($_SERVER["HTTP_CF_CONNECTING_IP"])) {
$_SERVER['REMOTE_ADDR'] = $_SERVER["HTTP_CF_CONNECTING_IP"];
}
return $_SERVER['REMOTE_ADDR'];
}
$allowed = array('77.83.102.155');
if (!in_array(getIP(), $allowed)) die("hacking attempt!");Сповіщення про платіж
Після ініціалізації оплати користувач переходить на сторінку чеку, де відбувається відстеження статусу платежу. При отриманні успішного або помилкового статусу користувач перенаправляється на сайт партнера (поля Fail URL / Success URL у налаштуваннях кабінету) з POST-параметрами:
| Параметр | Примітка |
|---|---|
| sum | Сума платежу. |
| invoice | Номер рахунку. |
| http_auth_signature | Підпис, згенерований у MD5 || SHA1 || SHA256 || SHA512 || SHA384 || RIPEMD160 із секретним ключем. |
Приклад обробника платежу
Рекомендується також перевіряти суму платежу та те, що запит ще не був оплачений.
Приклад обробника на PHP:
function getIP() {
if (isset($_SERVER['HTTP_X_REAL_IP'])) return $_SERVER['HTTP_X_REAL_IP'];
if (isset($_SERVER['HTTP_CF_CONNECTING_IP'])) return $_SERVER['HTTP_CF_CONNECTING_IP'];
return $_SERVER['REMOTE_ADDR'];
}
$allowed = array('77.83.102.155');
if (!in_array(getIP(), $allowed)) die("hacking attempt!");
$sign = hash('sha256', "ID_магазину:Сума:Секретний_ключ:Номер_рахунку");
if ($sign !== $_POST['http_auth_signature']) die('Error signature');