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

Для зручної роботи з API ми надали інтерактивну Swagger документацію, яка дозволяє переглядати всі доступні API endpoints, бачити параметри запитів та приклади відповідей, тестувати API прямо в браузері та імпортувати специфікацію в Postman та інші інструменти.

Swagger документація:

https://aifo.pro/docs/swagger

Swagger документація містить всю інформацію про API endpoints, які описані нижче, але в більш зручному та інтерактивному форматі. Рекомендуємо використовувати Swagger для розробки та тестування інтеграцій.

JSON специфікація доступна за адресою: https://aifo.pro/docs/swagger/spec

Створення платежу

Для ініціалізації платежу через єдину форму оплати достатньо направити користувача за спеціальною URL-адресою, а також передати ряд обов’язкових параметрів.

URL форми оплати:

https://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 Коментар до платежу. Необов’язковий.

Підпис для створення платежу формується шляхом обчислення SHA256 || SHA1 || SHA512 || SHA384 || RIPEMD160-хешу. Рекомендується SHA256.

Увага: MD5 застарілий і небезпечний. Використовуйте SHA256 або інші безпечні алгоритми.

Важливо: Для генерації підпису використовуйте секретний ключ (kassa_secretkey), а не публічний ключ. Секретний ключ доступний тільки вам і не повинен публікуватися.

Приклад коду на PHP (підпис):

PHP 
// SHA256 (рекомендовано)
$sign = hash('sha256', "ID_магазину:Сума:секретний_ключ:Номер_рахунку");

// SHA1
$sign = hash('sha1', "ID_магазину:Сума:секретний_ключ:Номер_рахунку");

// SHA384, SHA512, RIPEMD160 — аналогічно, замініть 'sha256' на 'sha384' / 'sha512' / 'ripemd160'

Перевірка IP

Рекомендуємо перевіряти IP сервера, що надсилає інформацію. Наші IP — 77.83.102.155

Приклад коду на PHP:

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:

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');

// Далі — оновлення статусу замовлення, зарахування коштів тощо.