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

Ключи

После модерации проекта бот PayAPI пришлёт вам в Telegram два значения. Они и есть ваш доступ к API.

Секрет засветился — перевыпустите пару ключей в кабинете, старая перестанет работать сразу.

Подпись запросов

Каждый запрос подписан вашим секретом. Это защищает от трёх вещей: подделки запроса, подмены суммы по дороге и повторной отправки перехваченного запроса. Подпись — четыре заголовка:

Строка для подписи — пять строк, разделитель — перевод строки \n:

POST                                  ← метод заглавными
/v1/invoices                          ← путь без адреса сервера и без ?параметров
1790950000                            ← X-Hub-Timestamp
3b1f0c9e8a7d6c5b4a3f2e1d0c9b8a7f      ← X-Hub-Nonce
e3b0c44298fc1c149afbf4c8996fb924…     ← sha256 тела запроса в hex (для запроса без тела — sha256 пустой строки)

Важно: подписывается тело ровно в том виде, в каком оно отправляется. Соберите JSON в строку один раз, посчитайте от неё хеш и отправьте ту же строку.

Готовая функция запроса

Одна функция call() — и дальше все запросы к API делаются в одну строку. Скопируйте, подставьте ключи, запустите.

import hmac, hashlib, json, time, secrets, requests   # requests: pip install requests

BASE = "https://адрес-api"       # адрес API
KEY = "mer_7f3a9c21d04e8b65"                           # ваш hub_key из сообщения в Telegram
SECRET = "ваш hub_secret"                              # только на сервере, не в коде приложения для покупателей

def call(method, path, body=None):
    raw = json.dumps(body).encode() if body is not None else b""   # тело ровно в том виде, в каком отправим
    ts = str(int(time.time()))                                       # время отправки, секунды
    nonce = secrets.token_hex(16)                                    # случайная строка, у каждого запроса своя
    msg = "\n".join([method, path, ts, nonce, hashlib.sha256(raw).hexdigest()])   # пять строк для подписи
    sig = hmac.new(SECRET.encode(), msg.encode(), hashlib.sha256).hexdigest()    # подпись секретом
    headers = {"X-Hub-Key": KEY, "X-Hub-Timestamp": ts, "X-Hub-Nonce": nonce,
               "X-Hub-Signature": sig, "Content-Type": "application/json"}
    return requests.request(method, BASE + path, data=raw, headers=headers).json()

# 1. Счёт на 500 рублей за заказ order-1001
invoice = call("POST", "/v1/invoices", {"order_id": "order-1001", "amount": 500, "currency": "rub"})
print(invoice["pay_url"])          # сюда отправляем покупателя

# 2. Позже — проверить, оплачен ли
status = call("GET", "/v1/invoices/" + invoice["invoice_id"])
print(status["status"])            # pending → paid

const crypto = require("crypto");                       // Node.js 18+, fetch встроен

const BASE = "https://адрес-api";   // адрес API
const KEY = "mer_7f3a9c21d04e8b65";                       // ваш hub_key из сообщения в Telegram
const SECRET = "ваш hub_secret";                          // только на сервере

async function call(method, path, body) {
  const raw = body ? JSON.stringify(body) : "";                           // тело ровно в том виде, в каком отправим
  const ts = Math.floor(Date.now() / 1000).toString();                   // время отправки, секунды
  const nonce = crypto.randomBytes(16).toString("hex");                  // случайная строка, у каждого запроса своя
  const hash = crypto.createHash("sha256").update(raw).digest("hex");    // хеш тела
  const msg = [method, path, ts, nonce, hash].join("\n");                // пять строк для подписи
  const sig = crypto.createHmac("sha256", SECRET).update(msg).digest("hex");   // подпись секретом
  const res = await fetch(BASE + path, { method, body: raw || undefined, headers: {
    "X-Hub-Key": KEY, "X-Hub-Timestamp": ts, "X-Hub-Nonce": nonce,
    "X-Hub-Signature": sig, "Content-Type": "application/json" } });
  return res.json();
}

// 1. Счёт на 500 рублей за заказ order-1001
const invoice = await call("POST", "/v1/invoices", { order_id: "order-1001", amount: 500, currency: "rub" });
console.log(invoice.pay_url);                 // сюда отправляем покупателя

// 2. Позже — проверить, оплачен ли
const status = await call("GET", "/v1/invoices/" + invoice.invoice_id);
console.log(status.status);                   // pending → paid

<?php
define("BASE", "https://адрес-api");   // адрес API
define("KEY", "mer_7f3a9c21d04e8b65");                       // ваш hub_key из сообщения в Telegram
define("SECRET", "ваш hub_secret");                          // только на сервере

function call($method, $path, $body = null) {
    $raw = $body === null ? "" : json_encode($body);                     // тело ровно в том виде, в каком отправим
    $ts = (string) time();                                               // время отправки, секунды
    $nonce = bin2hex(random_bytes(16));                                  // случайная строка, у каждого запроса своя
    $msg = implode("\n", [$method, $path, $ts, $nonce, hash("sha256", $raw)]);   // пять строк для подписи
    $sig = hash_hmac("sha256", $msg, SECRET);                            // подпись секретом
    $ch = curl_init(BASE . $path);
    curl_setopt_array($ch, [CURLOPT_CUSTOMREQUEST => $method, CURLOPT_POSTFIELDS => $raw,
        CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => [
        "X-Hub-Key: " . KEY, "X-Hub-Timestamp: $ts", "X-Hub-Nonce: $nonce",
        "X-Hub-Signature: $sig", "Content-Type: application/json"]]);
    return json_decode(curl_exec($ch), true);
}

// 1. Счёт на 500 рублей за заказ order-1001
$invoice = call("POST", "/v1/invoices", ["order_id" => "order-1001", "amount" => 500, "currency" => "rub"]);
echo $invoice["pay_url"];              // сюда отправляем покупателя

// 2. Позже — проверить, оплачен ли
$status = call("GET", "/v1/invoices/" . $invoice["invoice_id"]);
echo $status["status"];                // pending → paid

Что увидите в консоли

https://payapi.pro/pay/inv_6e852b738ce33a84f3c4c5e4
pending

Получили 401 или 403 вместо ссылки — смотрите код ошибки в разделе «Ошибки»: чаще всего это часы сервера (stale_or_bad_timestamp) или тело, изменённое после подсчёта хеша (bad_signature).

Создать счёт

Счёт — это «покупатель должен вам столько-то за такой-то заказ». Счёт живёт 2 часа. Повторный запрос с тем же order_id вернёт тот же счёт ("reused": true) — двойной оплаты за один заказ не будет, даже если ваш код отправит запрос дважды.

Ответ, если способ не указан — выберет покупатель

{
  "invoice_id": "inv_6e852b738ce33a84f3c4c5e4",     // наш номер счёта — по нему статус и уведомления
  "status": "pending",                               // ждём оплату
  "awaiting_method": true,                           // способ выберет покупатель на странице оплаты
  "amount": 500.0,
  "currency": "rub",
  "expires_at": 1790950000,                          // до какого времени счёт действует (unix-секунды)
  "pay_url": "https://payapi.pro/pay/inv_6e852b738ce33a84f3c4c5e4"   // ссылка для покупателя
}

Ответ, если способ указан — реквизиты уже готовы

{
  "invoice_id": "inv_6e852b738ce33a84f3c4c5e4",
  "status": "pending",
  "pay_url": "https://payapi.pro/pay/inv_6e852b738ce33a84f3c4c5e4",
  "pay_amount": "10.19",                   // сколько заплатит покупатель в валюте способа
  "pay_currency": "usdt",
  "fx_rate": "49.11",                      // курс пересчёта из валюты счёта
  "fee_payer": "merchant",                 // кто платит комиссию: вы или покупатель (настраивается в кабинете)
  "expected_net": "9.68",                  // сколько получите вы после комиссии — известно до оплаты
  "checkout_address": "TXk9…",             // адрес или реквизит для оплаты
  "checkout_amount": "10.19",
  "checkout_currency": "usdt",
  "requisite": { "type": "crypto", "address": "TXk9…", "receiver_name": null, "receiver_bank": null, "instruction": null },
  "expires_at": 1790950000
}

Сумма ниже минимума способа — ответ 400 amount_below_minimum с полем minimum. Способ не входит в ваш тариф — 403 method_not_in_tariff со списком allowed_methods.

Статус счёта

Единственный источник правды об оплате. Уведомление говорит «посмотрите», статус говорит «оплачено». Товар выдавайте по статусу.

Пример ответа

{
  "invoice_id": "inv_6e852b738ce33a84f3c4c5e4",
  "order_id": "order-1001",
  "status": "paid",
  "amount": 500.0,  "currency": "rub",              // что выставили
  "paid_amount": 10.19,  "paid_currency": "usdt",   // чем и сколько заплатил покупатель
  "checkout_address": "TXk9…",  "checkout_amount": 10.19,  "checkout_currency": "usdt",
  "requisite": { "type": "crypto", "address": "TXk9…", "receiver_name": null, "receiver_bank": null, "instruction": null },
  "sub_account": null,
  "expires_at": 1790950000
}

Покупатель заплатил после истечения срока — счёт всё равно станет paid: мы перепроверяем истёкшие счета ещё сутки.

Уведомления об оплате

Адрес уведомлений задаётся в кабинете. На него мы отправляем POST с JSON и теми же четырьмя заголовками, что и в ваших запросах — подпись считается вашим hub_secret по тому же правилу (путь — путь вашего адреса без домена). Так вы отличаете наше уведомление от чужой подделки.

Тело уведомления

{
  "event_id": "evt_3f9a1c…",          // номер события — одно событие обрабатывайте один раз
  "event": "invoice.paid",
  "invoice_id": "inv_6e852b738ce33a84f3c4c5e4",
  "order_id": "order-1001",            // ваш номер заказа
  "amount": 500.0,
  "currency": "rub",
  "paid_amount": 10.19,
  "paid_currency": "usdt",
  "sub_account": null
}

Ответьте 200 — и мы считаем уведомление доставленным. Другой ответ или нет ответа — повторим: через 1 минуту, 5, 15, час, 3 часа, 6, 12 и 24 часа. Восемь попыток за двое суток.

Проверка подписи уведомления (Python)

def verify(headers, path, raw_body: bytes) -> bool:
    # path — путь вашего адреса уведомлений, например "/payapi/notify"; raw_body — тело запроса как пришло, байтами
    msg = "\n".join(["POST", path, headers["X-Hub-Timestamp"], headers["X-Hub-Nonce"],
                     hashlib.sha256(raw_body).hexdigest()])                    # те же пять строк
    good = hmac.new(SECRET.encode(), msg.encode(), hashlib.sha256).hexdigest()  # какой должна быть подпись
    fresh = abs(time.time() - int(headers["X-Hub-Timestamp"])) <= 60          # не старше минуты
    return fresh and hmac.compare_digest(good, headers["X-Hub-Signature"])     # сравнение без утечки по времени

Оплата на своей странице

Не хотите отправлять покупателя на нашу страницу? Создайте счёт без method, покажите покупателю список способов у себя и сообщите нам его выбор. В ответ получите реквизиты и покажете их сами.

Баланс и история

Чтение данных своего проекта по API. Вместо {hub_key} подставьте свой hub_key.

Способы оплаты и валюты

Код способа — в поле method. Какие доступны вам — зависит от тарифа; точный список для счёта отдаёт GET /v1/invoices/{invoice_id}/methods.

sbpСБП

cardБанковская карта

crypto_usdtUSDT (TRC-20)

crypto_usdt_tonUSDT (TON)

crypto_usdt_solUSDT (Solana)

crypto_usdt_ethUSDT (ERC-20)

crypto_usdt_bnbUSDT (BEP-20)

crypto_btcBitcoin

crypto_ethEthereum

crypto_ltcLitecoin

crypto_trxTRON (TRX)

crypto_bnbBNB

crypto_tonGram (TON)

Валюты счёта (поле currency):

usd usdt rub eur try gbp uah byn kzt uzs gel amd kgs tjs pln cny krw thb myr idr inr aed ngn bdt

Мультибот: ваш бот работает через нас

Мультибот — это ваш собственный бот (ваш код, ваш сервер), который работает сразу на многих ботах-зеркалах Telegram. Вы меняете в коде две вещи: адрес Telegram API и токен. Всё остальное — как раньше.

Одна строка для вашей библиотеки

Кому подойдёт, а кому нет

Что работает как обычно

getUpdates (в том числе долгий опрос до 50 секунд), setWebhook на ваш адрес (только https), все методы отправки и редактирования, кнопки и callback, inline-режим, платежи в Stars, файлы (getFile и скачивание), команды и описание бота — они применяются ко всем зеркалам сразу.

Что надо знать

Ошибки

Ошибка — это HTTP-код не 200 и JSON вида {"error": "код", "message": "пояснение"}. Коды стабильны, на них можно опираться в программе.