PaygatePaygate
Войти Регистрация

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

Базовый цикл: создать инвойс → отправить клиента на страницу оплаты → получить подписанный webhook. Префикс /v1. Аутентификация — заголовок X-Api-Key.

OpenAPI 3 спека (JSON) Получить ключи

Поддерживаемые сети

ton
tron
solana
evm
bsc
polygon
arbitrum
optimism
base
avalanche
hyperevm
sonic
cronos
gnosis
linea
scroll
zksync
mantle
celo
blast
sei
berachain
moonbeam
btc
doge
ltc
monero

Переезд с другой платёжки — без переписывания кода

Уже интегрированы с Cryptomus / NOWPayments / Coinbase Commerce? Смените в SDK только base-URL и ключ — мы принимаем их формат create-invoice, отдаём нашу страницу оплаты в их формате ответа и шлём вебхук в их схеме с подписью, так что ваш verify-код работает как есть. Сопоставление по order_id.

# было:  https://api.cryptomus.com/v1/payment
# стало:  https://paygate.love/compat/cryptomus/v1/payment
# ключ: ваш paygate API-ключ; секрет вебхука = ваш paygate apiSecret
cryptomus✅ /compat/cryptomus
heleket✅ /compat/heleket
nowpayments✅ /compat/nowpayments
oxapay✅ /compat/oxapay
cryptocloud✅ /compat/cryptocloud
coinbase✅ /compat/coinbase
plisio✅ /compat/plisio
coinpayments✅ /compat/coinpayments
opennode✅ /compat/opennode
confirmo✅ /compat/confirmo
btcpay✅ /compat/btcpay
bitpay✅ /compat/bitpay
enot✅ /compat/enot
0xprocessing✅ /compat/0xprocessing
2328✅ /compat/2328
cispay✅ /compat/cispay
lava✅ /compat/lava
pawpayments✅ /compat/pawpayments
zenobank✅ /compat/zenobank
aaio✅ /compat/aaio
coingate✅ /compat/coingate
cryptobot✅ /compat/cryptobot

Нужен другой процессор — напишите, добавим адаптер (это один модуль).

Приём оплаты внутри вашего Telegram-бота

Ваш бот — мерчант? Не уводите пользователя на сайт или в чужой кошелёк-бот. Бот дёргает наш API, показывает адрес + сумму + QR прямо в чате и сам меняет сообщение на «✅ Оплачено», как только платёж подтвердится в сети. Тот же in-bot UX, что у CryptoBot, но крипта идёт напрямую вам, ключи ваши, комиссия — копейки.

1. POST /v1/invoices               # ваш API-ключ → { id, pay_address, pay_uri, amount_expected }
2. bot.sendPhoto( https://paygate.love/i/<id>/qr.png )   # публичный QR, Telegram сам его фетчит
   + кнопка «Открыть кошелёк» → pay_uri
3. наш вебхук invoice.paid → bot.editMessage → «✅ Оплачено»

Пользователь вообще не покидает бота мерча. QR-ручка /i/<id>/qr.png публичная (кодирует только адрес). Готовый copy-paste пример (grammy/telegraf) — в docs/BOT-INTEGRATION.md.

Для стримеров: донат-алерты, цель сбора, лидерборд

Все стримерские ручки ниже используют alert-токен — он уже вшит в ссылки оверлея и лидерборда на странице «Алерты» кабинета. Это read-only-возможность: API-ключ он не заменяет, но ссылку виджета публично не выкладывайте. Под капотом донат — это обычный инвойс с именем и сообщением донатера.

Как подключить донаты на стриме — по шагам

  1. Зарегистрируйтесь как стример: на странице регистрации выберите тип аккаунта «Стример / блогер» — кабинет настроится под донаты.
  2. Откройте Кабинет → «Алерты»: там живут ссылка оверлея (/alerts/widget?token=…), настройки вида алертов и редактор цели. Скопируйте ссылку оверлея.
  3. В OBS/Streamlabs: Sources → «+» → Browser Source → вставьте ссылку, задайте размер холста (например 1920×1080) → OK. Алерты и полоса цели теперь рендерятся на стриме; проверьте кнопкой тестового доната.
  4. Задайте цель сбора на той же странице «Алерты» — название, сумма и валюта. Прогресс-бар появится в оверлее и в GET /alerts/goal.
  5. Создайте донат-ссылку (Кабинет → «Ссылки»), поделитесь ссылкой/QR со зрителями и запостите публичный лидерборд /d/<token> в своём канале.
  6. Продвинутое: заливайте донаты с других платформ через POST /v1/donations/external или питайте сторонний прогресс-бар из GET /alerts/goal — детали ниже.

OBS-оверлей (Browser Source)

Готовая HTML-страница с живыми донат-алертами и полосой цели — добавьте её в OBS/Streamlabs как Browser Source:

https://paygate.love/alerts/widget?token=<alertToken>

Цель сбора — JSON для любого прогресс-бара (pull)

Публичный JSON текущей цели (токен — и есть доступ; кэш ~5 с). Любой сторонний виджет прогресс-бара может поллить эту ручку и показывать общий итог где угодно — так фандрайзер paygate подключается к чужой полосе.

curl "https://paygate.love/alerts/goal?token=<alertToken>"
→ { "active": true, "title": "New PC", "target": 1000,
    "current": 337.5, "currency": "USD" }
# цель не задана → { "active": false }

Внешние донаты — объединить источники в одной полосе (push)

Запишите донат, случившийся в другом месте (PayPal, DonationAlerts, вручную), чтобы он засчитался в ТУ ЖЕ полосу цели и, по желанию, вызвал тот же OBS-алерт. Одна полоса — все источники: крипта плюс всё, что вы сюда пушите. Авторизация: ваш API-ключ.

curl -X POST https://paygate.love/v1/donations/external \
  -H "X-Api-Key: pk_..." -H "Content-Type: application/json" \
  -d '{ "amount": 5, "currency": "USD", "name": "Alice",
        "message": "gg!", "source": "paypal", "fire_alert": true }'
→ 201 { "ok": true, "amount_usd": 5 }

Поля: amount (>0, обязательное), currency (по умолчанию USD), name (≤60), message (≤300), source (≤40, по умолчанию "api"), fire_alert (по умолчанию true). Сумма конвертируется в USD для итога цели.

Живой поток алертов (SSE)

Server-Sent Events с каждым донатом — соберите полностью свой оверлей вместо нашего виджета:

const es = new EventSource(
  "https://paygate.love/alerts/stream?token=<alertToken>");
es.onmessage = (e) => {
  const d = JSON.parse(e.data); // { name, amount, currency, asset, message }
  showAlert(d);
};

Публичный лидерборд

Шарибельная публичная страница топ-донатеров (топ, последние донаты, цель) — запостите её в описании канала или в чате:

https://paygate.love/d/<alertToken>

Выплаты: по умолчанию донаты кастодиальные — выводите из кабинета когда угодно. Либо добавьте xpub своего кошелька в кабинете (non-custodial) — и донаты будут падать сразу в ваш кошелёк в EVM / TRON / BTC / LTC / DOGE.

Реферальная программа

Приглашайте магазины и стримеров — и получайте долю нашей комиссии с каждого их платежа, пожизненно. Ставка по умолчанию — 20%, и она может выставляться индивидуально для каждого партнёра.

https://paygate.love/?ref=<yourCode>

Ваша уникальная ссылка — в Кабинете → «Рефералы». Каждый, кто зарегистрируется по ней (код ?ref= подхватывается через cookie, либо вводится в необязательное поле на форме регистрации), закрепляется за вами навсегда.

Начисления происходят автоматически по каждому подтверждённому (оплаченному) инвойсу приглашённого мерчанта, в USD; статистика и суммы — в Кабинете → «Рефералы».

💸 Prepaid-кошелёк донатера (мгновенные донаты)

Зритель пополняет кошелёк один раз (крипта подтверждается один раз), а потом шлёт мгновенные донаты любому стримеру Paygate из внутреннего баланса — алерт всплывает сразу, без ожидания подтверждения сети на каждый донат. Донаты падают в ваш обычный баланс, выводите как всегда. Страница кошелька: /w (ссылка на предъявителя, токен в #fragment — не попадает в логи).

🧩 Установка плагинов

Перед началом возьмите API-ключ и secret на странице «Настройки» вашего магазина. ⚙️

🛒 WooCommerce — установка

  1. Скачайте zip плагина (кнопка «Скачать» на странице Плагины или в кабинете).
  2. WP-админка → Плагины → Добавить новый → Загрузить плагин → выберите zip → Установить → Активировать.
  3. WooCommerce → Настройки → Платежи → включите «Paygate (crypto)» и нажмите «Управление».
  4. Вставьте API-ключ и secret, сохраните. Webhook подтянется автоматически.
  5. Сделайте тестовый заказ: на оформлении выберите «Paygate», оплатите — заказ перейдёт в «Оплачен» по подписанному webhook.

🖥️ WHMCS — установка

  1. Скачайте и распакуйте zip. Внутри — папка modules/gateways/.
  2. Загрузите содержимое modules/gateways/ в корень вашей установки WHMCS (сольётся с существующей структурой).
  3. WHMCS-админка → Настройки → Платежи (Payment Gateways) → вкладка «All Payment Gateways» → активируйте «Paygate».
  4. Введите API-ключ и secret, сохраните. Проверьте на тестовом инвойсе — статус обновится по callback.

🛍️ OpenCart — установка

  1. Скачайте zip. Скопируйте содержимое upload/ в корень OpenCart (сольётся с admin/ и catalog/), либо установите zip через Extensions → Installer.
  2. Расширения → Расширения → Оплата → найдите «Paygate — Crypto Payments» → «+» (Установить) → карандаш (Редактировать).
  3. Статус = Включено, вставьте API-ключ и secret, выберите статусы заказа, сохраните. Webhook пропишется автоматически (callback_url).
  4. Тестовый заказ: на оформлении выберите «Pay with Crypto», оплатите — статус обновится по подписанному webhook.

🧿 PrestaShop — установка

  1. Скачайте zip модуля. Бэк-офис → Модули → Менеджер модулей → «Загрузить модуль» → выберите zip → установить.
  2. Нажмите «Настроить», вставьте API-ключ и secret (base URL оставьте https://paygate.love), сохраните.
  3. Webhook пропишется автоматически (callback_url) и показан на странице настроек.
  4. Тестовый заказ: выберите «Pay with Crypto», оплатите — заказ перейдёт в «Оплата принята» по подписанному webhook.

🅜 Magento 2 — установка

  1. Скопируйте папку Paygate в app/code/ (модуль: app/code/Paygate/Crypto).
  2. Из корня Magento: bin/magento module:enable Paygate_Crypto && bin/magento setup:upgrade && setup:di:compile && cache:flush.
  3. Admin → Stores → Configuration → Sales → Payment Methods → «Paygate — Crypto Payments»: Enabled = Yes, вставьте API-ключ и secret, сохраните.
  4. Webhook: https://ваш-магазин/paygate/webhook (шлётся автоматически как callback_url). Проверьте тестовым заказом.

🛒 CS-Cart — установка

  1. Скачайте zip. Администрирование → Модули → Управление модулями → «+» (Загрузить и установить) → выберите zip.
  2. Администрирование → Способы оплаты → Добавить: Процессор = «Paygate (crypto)».
  3. Во вкладке «Настройка» вставьте API-ключ и secret (base URL оставьте https://paygate.love), сохраните и активируйте.
  4. Webhook пропишется автоматически (callback_url). Проверьте тестовым заказом — статус обновится по подписанному webhook.

🅱️ Blesta — установка

  1. Скачайте zip. Скопируйте components/gateways/nonmerchant/paygate/ в вашу установку Blesta по тому же пути.
  2. Settings → Company → Payment Gateways → Available → установите «Paygate — Crypto Payments».
  3. Нажмите «Manage», вставьте API-ключ и secret (base URL оставьте https://paygate.love), сохраните.
  4. Callback-URL — стандартный шлюзовой Blesta, шлётся автоматически. Проверьте на тестовом инвойсе.

🧾 FOSSBilling — установка

  1. Скачайте zip и распакуйте library/Payment/Adapter/Paygate.php в корень вашей установки FOSSBilling (путь сольётся).
  2. Админка → System → Payment gateways → New payment gateway → активируйте «Paygate».
  3. Вставьте API-ключ и secret (base URL оставьте https://paygate.love), сохраните.
  4. Webhook (IPN) шлётся автоматически как callback_url. Проверьте тестовым инвойсом — оплата применится по подписанному вебхуку.

💬 XenForo — установка

  1. Скачайте zip и скопируйте содержимое upload/ в корень форума (появится src/addons/Paygate/Crypto).
  2. Admin → Add-ons → установите «Paygate — Crypto Payments».
  3. Admin → Setup → Payment profiles → Add payment profile → Paygate: вставьте API-ключ и secret, сохраните.
  4. Подключите профиль к User upgrades. Оплата подтверждается подписанным webhook через payment_callback.php.

📦 BoxBilling — установка

  1. Скачайте zip и распакуйте bb-library/Payment/Adapter/Paygate.php в корень установки BoxBilling.
  2. Админка → Configuration → Payment gateways → New payment gateway → активируйте «Paygate».
  3. Вставьте API-ключ и secret (base URL — https://paygate.love), сохраните. Webhook (IPN) подключится автоматически.
  4. Проверьте тестовым инвойсом — оплата применится по подписанному вебхуку.

🎮 Paymenter — установка

  1. Скачайте zip и распакуйте extensions/Gateways/Paygate в корень Paymenter.
  2. Админка → Extensions → Gateways → включите «Paygate».
  3. Вставьте API-ключ и secret (base URL — https://paygate.love), сохраните.
  4. Webhook: /extensions/gateways/paygate/webhook (шлётся автоматически как callback_url). Проверьте тестовым инвойсом.

👥 Invision Community — установка

  1. Скачайте zip и установите приложение paygate (AdminCP → System → Applications; см. README для dev-mode/сборки tar).
  2. AdminCP → Commerce → Payments → Payment Methods → Create New → Paygate.
  3. Вставьте API-ключ и secret (base URL — https://paygate.love), сохраните.
  4. Оплата подтверждается подписанным webhook; underpaid уходит в Held на ручную проверку.

📋 vBulletin — установка (vB4 / vB5)

  1. Выберите свой архив: vB4 (4.2.x) → includes/paymentapi/class_paygate.php; vB5 → core/includes/paymentapi/class_paygate.php.
  2. Скопируйте файл класса по нужному пути и выполните install.sql из архива (регистрирует метод в таблице paymentapi).
  3. AdminCP → Paid Subscriptions → Payment API Manager → Paygate: включите, вставьте API-ключ и secret (base URL — https://paygate.love).
  4. Подписка активируется по подписанному webhook (payment_gateway.php); дубли отбиваются по transaction id.

🎮 Azuriom — установка

  1. Скачайте zip и добавьте PaygateMethod в плагин Shop (см. README: патч в PaymentManager или регистрация через registerPaymentMethod).
  2. Админка → Shop → Настройки → Payment gateways → Paygate: вставьте API-ключ и secret (base URL — https://paygate.love).
  3. Оплата подтверждается подписанным webhook (shop.payments.notification); завершённый платёж идемпотентен.

🏬 Webasyst / Shop-Script — установка

  1. Скачайте zip и распакуйте wa-plugins/payment/paygate в корень Webasyst.
  2. Магазин → Настройки → Оплата → добавить способ → Paygate: вставьте API-ключ и secret (base URL — https://paygate.love).
  3. Оплата подтверждается подписанным webhook (relay-URL waPayment); дедуп по native_id.

🛒 X-Cart — установка

  1. Скачайте zip и распакуйте classes/ и skins/ в корень X-Cart, затем пересоберите кэш (Re-deploy).
  2. Админка → Store setup → Payment methods → включите «Paygate».
  3. Вставьте API-ключ и secret (base URL — https://paygate.love), сохраните. Оплата подтверждается подписанным webhook.

🛍️ Zen Cart — установка

  1. Скачайте zip: файл модуля в includes/modules/payment/, язык в includes/languages/english/modules/payment/, ipn_paygate.php — в корень магазина.
  2. Админка → Modules → Payment → Paygate → Install; вставьте API-ключ и secret (base URL — https://paygate.love).
  3. Заказ создаётся в pending, статус обновляется по подписанному webhook (ipn_paygate.php).

🏪 osCommerce — установка

  1. Скачайте zip (цель — osCommerce 2.3.x): файл модуля в includes/modules/payment/, callback.php в ext/modules/payment/paygate/, язык в includes/languages/english/....
  2. Admin → Modules → Payment → Paygate → Install; вставьте API-ключ и secret (base URL — https://paygate.love).
  3. Статус заказа обновляется по подписанному webhook (ext/.../callback.php); при неоплате вебхук ретраится.

🛒 VirtueMart (Joomla) — установка

  1. Joomla → Расширения → Установить: загрузите zip (или скопируйте в plugins/vmpayment/paygate/ и нажмите Discover).
  2. Включите плагин «VM Payment - Paygate», затем VirtueMart → Способы оплаты → создайте метод на его основе.
  3. Вставьте API-ключ и secret (base URL — https://paygate.love), сохраните. Оплата подтверждается подписанным webhook.

💧 Drupal Commerce — установка

  1. Распакуйте модуль в modules/custom/paygate (или composer), включите на Extend.
  2. Commerce → Configuration → Payment gateways → Add: выберите Paygate (off-site redirect).
  3. Вставьте API-ключ и secret (base URL — https://paygate.love), сохраните. Источник истины — notify-webhook.

⬇️ Easy Digital Downloads — установка

  1. WP-админка → Плагины → Добавить новый → Загрузить → выберите zip → Установить → Активировать.
  2. Downloads → Settings → Payment Gateways → включите «Paygate» и откройте его настройки.
  3. Вставьте API-ключ и secret (base URL — https://paygate.love), сохраните. Оплата подтверждается подписанным webhook (edd-listener).

🧾 HostBill — установка (бесплатный мост)

  1. Это лёгкий мост, а не платный SDK-модуль: распакуйте архив в веб-доступную папку, напр. https://ваш-биллинг/paygate/.
  2. HostBill → Settings → API: создайте API-пользователя, впишите IP этого сервера в whitelist. Скопируйте config.sample.php → config.php и заполните ключи HostBill + Paygate + случайный link_secret.
  3. В настройках магазина Paygate укажите webhook/callback → https://ваш-биллинг/paygate/callback.php. Оплата закрывает инвойс автоматически через Admin API (addInvoicePayment).
  4. Кнопку «Pay with Crypto» на инвойсе добавьте хуком hooks/paygate_button.php (в includes/hooks/) или готовой подписанной ссылкой pay.php?invoice_id=…&token=… — см. README.

🖥️ WISECP — установка

  1. Скопируйте папку coremio/ из архива поверх корня WISECP (модуль ляжет в coremio/modules/Payment/Paygate/).
  2. Админка → Settings → Payment Gateways → включите «Paygate — Crypto Payments» и вставьте API-ключ и secret (base URL — https://paygate.love).
  3. Webhook настраивать не нужно: модуль сам передаёт callback-ссылку при каждом чекауте. Оплата подтверждается подписанным webhook.

🧾 ClientExec — установка

  1. Распакуйте архив в plugins/gateways/paygate/ вашего ClientExec.
  2. Settings → Plugins → Payment Processors → активируйте Paygate и вставьте API-ключ и secret (base URL — https://paygate.love).
  3. Webhook: https://ваш-домен/plugins/gateways/paygate/callback.php — укажите его в настройках магазина Paygate.

🎨 Tilda — установка (универсальная платёжка)

  1. Это самостоятельный мост: распакуйте архив на свой PHP-хостинг (напр. https://ваш-домен/paygate/), заполните config.php по образцу.
  2. В Тильде: Настройки сайта → Платёжные системы → Универсальная платёжная система → API URL = https://ваш-домен/paygate/receive.php; поля и подпись — по README.
  3. Webhook Paygate: https://ваш-домен/paygate/callback.php. После оплаты мост сам шлёт подписанное уведомление в Тильду — заказ помечается оплаченным.

🛒 BigCommerce — установка (мост)

  1. Нативный список платёжек BigCommerce закрыт партнёркой, поэтому это мост: распакуйте архив на свой PHP-хостинг и заполните config.php.
  2. В BigCommerce создайте Store-level API-аккаунт (scope Orders), включите оффлайн-метод «Cryptocurrency (Paygate)» и добавьте кнопку оплаты по README (Script Manager).
  3. Webhook Paygate: https://ваш-домен/paygate/callback.php — после оплаты заказ автоматически переходит в Awaiting Fulfillment.

🛍️ Zid — установка (приватный мост)

  1. В App Store Zid крипту не пускают (SAMA), поэтому мост ставится приватно под ваши партнёрские креды. Разверните Node-сервис из архива (npm i && npm run build).
  2. Заполните .env (токены Zid, ключи Paygate), зарегистрируйте webhook на создание заказа по README.
  3. Покупатель платит по ссылке /pay/:orderId; после подтверждения мост помечает заказ оплаченным через API Zid.

1. Создать инвойс

POST /v1/invoices
X-Api-Key: pk_...
Idempotency-Key: order-1042        # необязательно, защищает от дублей
Content-Type: application/json

{ "network": "ton", "asset": "USDT", "amount": "25.00", "order_id": "1042" }

Ответ содержит id, pay_address, pay_uri, expires_at. Отправьте покупателя на /pay/.

Необязательные поля запроса: quote_currency (валюта суммы, по умолчанию USD), order_id, callback_url (вебхук для этого инвойса), success_url (куда вернуть покупателя), test (песочница). Полный ответ содержит также status, network, asset, amount_expected, rate_locked, fee_percent, telegram_url.

Песочница: добавьте "test": true — инвойс не отслеживается в блокчейне и не влияет на баланс; «оплату» можно симулировать в кабинете для проверки вебхуков. Вебхук такого инвойса подписан так же, но содержит "test": true — отгружайте товар только при test === false.

1b. Живой курс — цена в USD → сумма в BTC/LTC

GET /v1/quote?asset=BTC&quote_currency=USD
X-Api-Key: pk_...
→ { "asset": "BTC", "quote_currency": "USD", "rate": "63022.25" }

# price a $12.99 item in BTC:
#   amount = 12.99 / 63022.25 = 0.00020612  → send as "amount" to /v1/invoices
# optional: pass &amount=12.99 to get "quote_amount" back too

Сумма (amount) задаётся в валюте quote_currency (по умолчанию USD) — шлюз сам пересчитывает её в монету по живому курсу, считать вручную ничего не нужно. Для USDT/USDC при USD это 1:1. Чтобы задать сумму сразу в монете, укажите quote_currency равным символу монеты (например quote_currency=BTC) — тогда пересчёта нет. Курс тянется с CoinGecko/Coinbase, обновляется каждые ~45 сек и фиксируется в инвойсе (rate_locked), поэтому покупатель всегда платит корректную актуальную сумму. В ответе возвращаются quote_amount (как прислали) и amount_expected (итог в монете).

Не хотите считать сами? Используйте POST /v1/checkouts с суммой в USD — покупатель сам выберет монету, а конвертацию по живому курсу сделаем мы.

Платёжная ссылка (покупатель выбирает монету)

POST /v1/checkouts
X-Api-Key: pk_...
Content-Type: application/json

{ "amount": "25.00", "quote_currency": "USD", "order_id": "1042" }
→ { "checkout_url": "https://…/checkout/…", "short_url": "https://…/c/…",
    "telegram_url": "https://t.me/…", "expires_at": "…" }

POST /v1/checkouts с суммой создаёт ссылку, где сеть и монету выбирает покупатель — идеально без интеграции. Ответ: checkout_url, short_url, telegram_url, expires_at. Поддерживаются те же order_id, callback_url и success_url, что и у инвойса.

🤖 Приём оплаты в Telegram-боте / магазине

Продаёте прямо в Telegram? Не нужен свой сайт. Ваш бот создаёт чек через API и получает telegram_url — deep-link, который открывает оплату прямо внутри нашего Telegram-бота: покупатель выбирает монету/сеть, видит адрес и QR, платит. Вы получаете подписанный вебхук и выдаёте товар.

  1. Покупатель жмёт «Купить» в вашем боте → ваш бот вызывает POST /v1/checkouts (с order_id и callback_url).
  2. Ваш бот отвечает инлайн-кнопкой со ссылкой telegram_url (или short_url для оплаты на веб-странице).
  3. Покупатель оплачивает не выходя из Telegram → вам приходит вебхук invoice.paid → бот выдаёт товар/доступ.
// Telegram bot (grammY/Telegraf) — sell for crypto
bot.callbackQuery("buy", async (ctx) => {
  const r = await fetch("https://paygate.love/v1/checkouts", {
    method: "POST",
    headers: { "X-Api-Key": PK, "Content-Type": "application/json" },
    body: JSON.stringify({ amount: "9.99", quote_currency: "USD",
      order_id: ctx.from.id + ":" + Date.now(),
      callback_url: "https://my-bot.example/paygate-webhook" }),
  }).then((x) => x.json());
  // r.telegram_url opens the pay flow INSIDE Telegram (coin choice + address + QR)
  await ctx.reply("Оплатить криптой:", {
    reply_markup: { inline_keyboard: [[{ text: "💳 Pay", url: r.telegram_url }]] },
  });
});

// Deliver the goods on the signed webhook (see "Webhooks" below)
app.post("/paygate-webhook", (req, res) => {
  if (verifySignature(req) && req.body.event === "invoice.paid" && !req.body.test)
    deliverOrder(req.body.order_id);   // ship / grant access
  res.sendStatus(200);
});

Совет: используйте telegram_url для оплаты внутри Telegram, short_url — если хотите обычную веб-страницу оплаты. order_id привяжите к покупателю (chat id) и заказу, чтобы вебхук однозначно сматчился. Никогда не выдавайте товар, пока test=false.

2. Статус инвойса

GET /v1/invoices/<id>
X-Api-Key: pk_...
→ { "status": "paid", "amount_received": "25",
    "settlement": { "gross": "25", "fee": "…", "spread": "…", "net": "…", "revenue": "…" } }

Статусы: pending → detected → paid (а также underpaid, overpaid, expired, cancelled, settled).

Ещё эндпоинты

GET /v1/invoices — список инвойсов с пагинацией (limit до 200, offset, фильтр по status).
POST /v1/invoices/<id>/cancel — отменить pending/detected (шлёт invoice.cancelled).
GET /v1/quote?asset=&quote_currency=&amount= — предпросмотр курса и пересчёт суммы.
GET /v1/networks — список сетей и монет (без ключа).
GET /v1/reconciliation?from=&to= — сверка «выставлено vs получено» (лимит 30 запросов/мин).

Сверка: GET /v1/reconciliation?from=&to= — сколько выставлено vs получено (за вычетом комиссии) + расхождения по заказам (недоплаты/переплаты/неоплаченные). Мы — источник правды по факту оплаты; для non-custodial сверяйтесь по своему кошельку. Инструмент даёт данные — решения (отгрузка, споры) на вашей стороне.

3. Webhook

При смене статуса шлём POST на ваш webhook URL. Заголовок X-Signature = HMAC-SHA256(тело, api_secret). Проверьте подпись и свежесть (timestamp) до обработки.

Тело вебхука

{
  "event": "invoice.paid",
  "invoice_id": "inv_…", "order_id": "1042",
  "status": "paid", "test": false,
  "asset": "USDT", "network": "ton",
  "quote_currency": "USD",
  "amount_expected": "25", "amount_received": "25",
  "tx_hash": "…", "timestamp": "2026-07-12T20:00:00.000Z",
  "invoice": { "id": "inv_…", "order_id": "1042", "status": "paid",
               "quote_currency": "USD",
               "amount_expected": "25", "amount_received": "25" }
}

События: invoice.detected, invoice.paid, invoice.underpaid, invoice.overpaid, invoice.expired, invoice.cancelled. Заголовки: X-Signature, X-Webhook-Id, X-Event.

// Node — verify signature (constant-time), dedupe, gate on test
import crypto from "node:crypto";
const expected = crypto.createHmac("sha256", API_SECRET).update(rawBody).digest("hex");
const sig = String(req.headers["x-signature"] ?? "");
if (sig.length !== expected.length ||
    !crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected)))
  return res.sendStatus(401);
const evt = JSON.parse(rawBody);
if (Date.now() - new Date(evt.timestamp) > 5*60_000) return res.sendStatus(400); // anti-replay
if (seen(req.headers["x-webhook-id"])) return res.sendStatus(200);               // idempotency
if (evt.event === "invoice.paid" && evt.test === false) fulfil(evt.order_id);   // only real payments

Доставка: 3 быстрых попытки, затем очередь до 12 попыток с backoff до 1 часа. Дубли отсекайте по X-Webhook-Id. URL вебхука должен быть публичным http(s) — localhost/приватные адреса и редиректы отклоняются. Не отгружайте товар, пока test не равен false.

Хардненинг

Полный пример интеграции server-to-server (Node, без плагинов): merchant-backend.mjs
Получить ключи →