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

API для Telegram ботів - Інтегруйте платежі у ваш Telegram бот

Вступ

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

Створення платежів через бота
Сповіщення системи про оплату
Перевірки статусу платежів

✅ Уніфіковані параметри: Для створення платежів використовуються однакові параметри для веб-кас та Telegram-кас. Система автоматично визначає тип каси та формує правильний payment_url.

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

Важливо: endpoint /api/v1/telegram/webhook викликається вашим зовнішнім Telegram-ботом після підтвердження оплати. Це не нативний Telegram Payments webhook.

Базовий URL:

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

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

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

Новый API: используйте /api/v2/invoices/create, строковый external_id, amount_minor и HMAC SHA-256. Старый /api/v1/invoices/create остается для существующих интеграций.

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

Параметри:

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

HMAC: METHOD\nPATH\nTIMESTAMP\nNONCE\nSORTED_PARAMS. Legacy-подпись SHA256(shop_id:amount:secret_key:id) остается только для API v1 и прямых checkout-ссылок.

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

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

Приклад (Python):

Python

import requests
import time
import uuid
import hmac
import hashlib
from urllib.parse import urlencode

shop_id = 123
amount_minor = 10050
external_id = "TG-ORDER-12345"
secret_key = "your_secret_key"
timestamp = int(time.time())
nonce = str(uuid.uuid4())

payload = {
    "shop_id": shop_id,
    "amount_minor": amount_minor,
    "external_id": external_id,
    "description": "Telegram order #12345"
}

canonical = urlencode(sorted(payload.items()))
base = f"POST\n/api/v2/invoices/create\n{timestamp}\n{nonce}\n{canonical}"
signature = hmac.new(secret_key.encode(), base.encode(), hashlib.sha256).hexdigest()

response = requests.post(
    'https://aifo.pro/api/v2/invoices/create',
    json=payload,
    headers={
        "X-AIFO-Signature": signature,
        "X-AIFO-Timestamp": str(timestamp),
        "X-AIFO-Nonce": nonce
    }
)
data = response.json()
if data['status'] == 'success':
    
    invoice_id = data['data']['invoice_id']
    payment_url = data['data']['payment_url']
    print(f"Invoice created: invoice_id={invoice_id}")
    print(f"Payment URL: {payment_url}")



    
        
            2. Webhook - Сповіщення про оплату
        
        
            Коли користувач оплатив платіж у вашому Telegram боті, ви повинні відправити webhook на наш сервер, щоб система зарахувала кошти та відправила callback на ваш result_url.
            
                Важливо: Викликайте цей endpoint тільки з серверної сторони бота і ніколи не розкривайте secret_key користувачу.
            
            
            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("Payment processed, callback sent")
            
            
            
                Важливо:
                
                    Перевірить підпис та параметри
                    Зарахує кошти на баланс мерчанта
                    Відправить 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).
            Для перевірки статусу amount у запит не передається, але підпис рахується із сумою вже створеного рахунку.
            Приклад (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"Status: {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):
    """Create a signature for API requests.
    
    For invoice creation: use your order_id.
    For webhook/check: use invoice_id, the system ID from the API response.
    """
    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  
    
    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'Payment from @{message.from_user.username}'
    })
    d = r.json()
    if d['status'] == 'success':
        
        invoice_id = d['data']['invoice_id']
        await message.answer(
            f"Invoice created\nAmount: {amount} UAH\n"
            f"System ID: {invoice_id}\nWaiting for payment..."
        )
        

async def send_payment_webhook(invoice_id, amount, user_id, username):
    
    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 = 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"Status: {d['data']['status_text']}")

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