Вступ

Це API дозволяє інтегрувати платіжну систему у ваш Telegram бот. Після створення мерчанта типу "Telegram канал", ви можете використовувати ці endpoints для:

  • Створення платежів через бота
  • Сповіщення системи про оплату
  • Перевірки статусу платежів
✅ Уніфіковані параметри: Для створення платежів використовуються однакові параметри для веб-кас та Telegram-кас. Система автоматично визначає тип каси та формує правильний payment_url.
Сторінки оплати /pay та /payt приймають pay_id у двох форматах: спочатку пошук за вашим ID замовлення (виджет або пряме посилання), потім за системним invoice_id (посилання з API). Рекомендується використовувати payment_url з відповіді API.

Базовий URL:

https://aifo.pro/api/v1/telegram/

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

Для створення платежу використовуйте стандартний API endpoint:

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

Параметри:

Параметр Опис Тип
shop_id ID вашого Telegram мерчанта Обов'язковий
amount Сума платежу Обов'язковий
id Числовий ID платежу у вашій системі (обов'язковий). Зберігається в системі як invoice_uid для зворотної сумісності Обов'язковий
sign Підпис запиту. Рекомендовано SHA256; також SHA1, SHA384, SHA512, RIPEMD160 Обов'язковий
desc Опис платежу (може містити будь-який текст, пробіли, кирилицю) Необов'язковий

Формула підпису: SHA256(shop_id:amount:secret_key:id). У формулі використовується id (ваш ID), не desc.

Уніфіковані параметри: Для веб-кас та Telegram-кас використовуються однакові параметри створення платежу. Система автоматично створює власний invoice_id (автоінкремент), який використовується в payment_url та для всіх подальших операцій. Ваш id зберігається в системі для зворотної сумісності.

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

Приклад (Python):

Python 
import requests
import hashlib

shop_id = 123
amount = 100.50
order_id = 12345  # Ваш ID замовлення
secret_key = "your_secret_key"

# Формуємо підпис з використанням вашого order_id
sign_string = f"{shop_id}:{amount}:Секретний ключ:{order_id}"
sign = hashlib.sha256(sign_string.encode()).hexdigest()

response = requests.post('https://aifo.pro/api/v1/invoices/create', json={
    'shop_id': shop_id,
    'amount': amount,
    'id': order_id,  # Ваш ID замовлення
    'sign': sign,
    'desc': 'Оплата замовлення №12345'
})
data = response.json()
if data['status'] == 'success':
    # Система створила власний invoice_id
    invoice_id = data['data']['invoice_id']
    payment_url = data['data']['payment_url']
    print(f"Платіж створено: invoice_id={invoice_id}")
    print(f"URL для оплати: {payment_url}")
    # Використовуйте invoice_id для перевірки статусу та webhook

2. Webhook - Сповіщення про оплату

Коли користувач оплатив платіж у вашому Telegram боті, ви повинні відправити webhook на наш сервер, щоб система зарахувала кошти та відправила callback на ваш result_url.

Endpoint:

POST https://aifo.pro/api/v1/telegram/webhook

Параметри:

Параметр Опис Тип
shop_id ID вашого Telegram мерчанта Обов'язковий
id ID платежу (invoice_id) - системний ID, отриманий при створенні платежу через API Обов'язковий
amount Сума оплати (повинна співпадати з сумою платежу) Обов'язковий
sign Підпис запиту Обов'язковий
telegram_user_id ID користувача Telegram (для статистики) Необов'язковий
telegram_username Username користувача Telegram Необов'язковий

Формула підпису: SHA256(shop_id:amount:secret_key:id). Використовується id (invoice_id - системний ID, отриманий при створенні платежу).

Приклад (Python):

Python 
import requests
import hashlib

shop_id = 123
invoice_id = 456
amount = 100.50
secret_key = "your_secret_key"

sign_string = f"{shop_id}:{amount}:Секретний ключ:{invoice_id}"
sign = hashlib.sha256(sign_string.encode()).hexdigest()

response = requests.post('https://aifo.pro/api/v1/telegram/webhook', json={
    'shop_id': shop_id,
    'id': invoice_id,
    'amount': amount,
    'sign': sign,
    'telegram_user_id': 123456789,
    'telegram_username': 'username'
})
data = response.json()
if data['status'] == 'success':
    print("Платіж оброблено, callback відправлено")
Важливо: Після відправки webhook система:
  • Перевірить підпис та параметри
  • Зарахує кошти на баланс мерчанта
  • Відправить POST запит на ваш result_url з даними платежу
Примітка: Для інтеграції з Monobank використовується офіційний Monobank Acquiring API. Webhook від Monobank автоматично обробляється системою та зараховує кошти на баланс.

3. Перевірка статусу платежу

Використовуйте цей endpoint для перевірки статусу платежу з вашого бота.

Endpoint:

GET/POST https://aifo.pro/api/v1/telegram/check

Параметри:

Параметр Опис Тип
shop_id ID вашого Telegram мерчанта Обов'язковий
id ID платежу (invoice_id) - числовий ідентифікатор Обов'язковий
sign Підпис запиту Обов'язковий

Формула підпису: SHA256(shop_id:amount:secret_key:id). amount — сума платежу при створенні, id — invoice_id (системний ID).

Приклад (Python):

Python 
import requests
import hashlib

shop_id = 123
invoice_id = 456
secret_key = "your_secret_key"
amount = 100.50

sign_string = f"{shop_id}:{amount}:Секретний ключ:{invoice_id}"
sign = hashlib.sha256(sign_string.encode()).hexdigest()

response = requests.post('https://aifo.pro/api/v1/telegram/check', json={
    'shop_id': shop_id,
    'id': invoice_id,
    'sign': sign
})
data = response.json()
if data['status'] == 'success':
    print(f"Статус: {data['data']['status_text']}")

Можливі статуси:

  • 0 / pending - Очікує оплати
  • 1 / paid - Оплачено
  • 2 / cancelled - Скасовано
  • 3 / test - Тестовий

4. Повний приклад Telegram бота (Python aiogram)

Приклад повної інтеграції (aiogram):

Python 
import asyncio, requests, hashlib
from aiogram import Bot, Dispatcher, types
from aiogram.filters import Command

SHOP_ID = 123
SECRET_KEY = "your_secret_key"
API_URL = "https://aifo.pro/api/v1"

def create_signature(shop_id, amount, secret_key, invoice_id):
    """Створює підпис для API запитів.
    
    Для створення платежу: використовуйте ваш order_id
    Для webhook/check: використовуйте invoice_id (системний ID з відповіді API)
    """
    s = f"{shop_id}:{amount}:Секретний ключ:{invoice_id}"
    return hashlib.sha256(s.encode()).hexdigest()

bot = Bot(token="YOUR_BOT_TOKEN")
dp = Dispatcher()

@dp.message(Command("buy"))
async def cmd_buy(message: types.Message):
    amount = 100.0
    order_id = 12345  # Ваш ID замовлення
    # Підпис для створення: використовуємо ваш order_id
    sign = create_signature(SHOP_ID, amount, SECRET_KEY, order_id)
    r = requests.post(f"{API_URL}/invoices/create", json={
        'shop_id': SHOP_ID, 'amount': amount, 'id': order_id,
        'sign': sign, 'desc': f'Платіж від @{message.from_user.username}'
    })
    d = r.json()
    if d['status'] == 'success':
        # Отримуємо системний invoice_id з відповіді
        invoice_id = d['data']['invoice_id']
        await message.answer(
            f"💳 Платіж створено!\nСума: {amount} UAH\n"
            f"Системний ID: {invoice_id}\nОчікуємо оплату..."
        )
        # Зберігаємо invoice_id для подальшого використання (webhook, check)

async def send_payment_webhook(invoice_id, amount, user_id, username):
    # Для webhook використовуємо invoice_id (системний ID) з відповіді API
    sign = create_signature(SHOP_ID, amount, SECRET_KEY, invoice_id)
    r = requests.post(f"{API_URL}/telegram/webhook", json={
        'shop_id': SHOP_ID, 'id': invoice_id, 'amount': amount, 'sign': sign,
        'telegram_user_id': user_id, 'telegram_username': username
    })
    return r.json()

@dp.message(Command("check"))
async def cmd_check(message: types.Message):
    # Для перевірки статусу використовуємо invoice_id (системний ID)
    invoice_id = 456  # Отриманий при створенні платежу
    amount = 100.50   # Сума при створенні
    sign = create_signature(SHOP_ID, amount, SECRET_KEY, invoice_id)
    r = requests.post(f"{API_URL}/telegram/check", json={
        'shop_id': SHOP_ID, 'id': invoice_id, 'sign': sign
    })
    d = r.json()
    if d['status'] == 'success':
        await message.answer(f"Статус: {d['data']['status_text']}")

if __name__ == '__main__':
    asyncio.run(dp.start_polling(bot))