AIFO | Приймати платежі може бути легко та швидко!

У нас є готові модулі, їх можна завантажити тут: Перейти
Новинка! API для Telegram ботів: Документація Telegram API

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

Основний API створення рахунку

Для web-каси і Telegram-каси використовуйте єдиний endpoint створення рахунку. У відповіді система поверне системний invoice_id і готове посилання payment_url.

Новый API для подключений: используйте /api/v2. Он поддерживает строковый external_id, сумму через amount_minor, HMAC SHA-256 и стабильные error_code. /api/v1 остается доступным для старых магазинов.

Для web-каси payment_url веде на /pay, для Telegram-каси - на /payt. Використовуйте посилання з відповіді API.

Endpoint:

POST https://aifo.pro/api/v2/invoices/create

Параметр	Примітка	Тип
`shop_id`	ID каси з кабінету мерчанта.	Обов'язковий.
`amount`	Сумма строкой: `100.50`. Можно заменить на `amount_minor`.	Обов'язковий.
`amount_minor`	Сумма в минимальных единицах: `10050` для 100.50. Приоритетнее `amount`.	Необов'язковий.
`external_id`	Ваш ID заказа строкой: `ORDER-123`, UUID или число. Хранится как `invoice_uid`.	Обов'язковий.
`X-AIFO-Signature`, `X-AIFO-Timestamp`, `X-AIFO-Nonce`	HMAC SHA-256 авторизация нового API.	Обов'язковий.
`description`	Коментар до платежу.	Необов'язковий.
`lifetime_minutes`	Час життя рахунку у хвилинах, від 0 до 43200. Необов'язково.	Необов'язковий.

HMAC canonical string: METHOD\nPATH\nTIMESTAMP\nNONCE\nSORTED_PARAMS. Старый sign=hash(shop_id:amount:secret_key:id) работает только в legacy API v1 и прямом checkout.

{
  "status": "success",
  "message": "Invoice created",
  "data": {
    "api_version": "v2",
    "invoice_id": 456,
    "external_id": "ORDER-123",
    "amount": "100.50",
    "amount_minor": 10050,
    "currency": "UAH",
    "merchant_type": "domain",
    "checkout_endpoint": "/pay",
    "status_text": "pending",
    "payment_url": "https://aifo.pro/pay?shop_id=123&pay_id=456&amount=100.50&sign=..."
  }
}

API перевірки статусу рахунку

Статус рахунку доступний тільки з shop_id і підписом. Це захищає платежі від перегляду лише за одним ID.

GET https://aifo.pro/api/v2/invoices/status?invoice_id=456&shop_id=123

Параметр	Примітка	Тип
`invoice_id`	Системный invoice_id из ответа API v2. Вместо него можно передать `external_id`.	Обов'язковий.
`shop_id`	ID каси з кабінету мерчанта.	Обов'язковий.
`X-AIFO-Signature`, `X-AIFO-Timestamp`, `X-AIFO-Nonce`	HMAC SHA-256 авторизация.	Обов'язковий.

Прямий checkout URL

Це старий прямий формат переходу на форму оплати. Для нових інтеграцій рекомендуємо спочатку створювати рахунок через /api/v1/invoices/create і використовувати payment_url з відповіді.

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

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

https://aifo.pro/pay/?shop_id=ID&pay_id=ORDER_ID&amount=AMOUNT&sign=SIGN

Форма оплати містить усі необхідні дані для проведення платежу. Передається методом GET/POST на адресу.

Параметр	Примітка	Тип
shop_id	ID каси, можна отримати в налаштуваннях проєкту.	Обов'язковий.
amount	Сума платежу.	Обов'язковий.
pay_id	Номер рахунку. Може бути ваш ID замовлення (виджет або пряме посилання) або системний invoice_id (посилання з API). Система спочатку шукає інвойс за вашим id (invoice_uid), потім за invoice_id.	Обов'язковий.
sign	Підпис платежу.	Обов'язковий.
desc	Коментар до платежу.	Необов'язковий.

Формат pay_id на сторінці /pay:

Ваш 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 (підпис):

PHP


$sign = hash('sha256', "SHOP_ID:AMOUNT:SECRET_KEY:ORDER_ID");


$sign = hash('sha1', "SHOP_ID:AMOUNT:SECRET_KEY:ORDER_ID");




    
        
            Перевірка 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', "SHOP_ID:AMOUNT:SECRET_KEY:ORDER_ID");
if ($sign !== $_POST['http_auth_signature']) die('Error signature');

Параметр	Примітка
sum	Сума платежу.
invoice	Номер рахунку.
http_auth_signature	Підпис, згенерований у MD5 \|\| SHA1 \|\| SHA256 \|\| SHA512 \|\| SHA384 \|\| RIPEMD160 із секретним ключем.