Быстрый старт: авторизация и первый счёт

GramPayBot API — небольшой JSON-API: создать счёт, узнать его статус, получить список счетов. Уведомления о смене статуса приходят через webhooks. В этом разделе — путь от токена до первой ссылки на оплату.

Где взять API-токен

Токен выдаётся на уровне проекта (приложения). Откройте бота → Мои приложения → выберите проект → 🔑 API → Создать токен. Токен имеет вид gp_live_… и показывается один раз — сохраните его в секретах приложения, не в коде.

Там же токен можно сменить (Сменить токен) или отключить API целиком. После смены токена старый перестаёт действовать.

Формат запросов

Все методы живут под /api, принимают и возвращают JSON. Токен передаётся в заголовке GramPay-API-Token:

GramPay-API-Token: gp_live_xxx
Content-Type: application/json

Каждый ответ — конверт с полем ok:

{ "ok": true,  "result": { … } }
{ "ok": false, "error": { "code": "UNAUTHORIZED", "message": "Invalid API token" } }

Первый вызов: createInvoice

Достаточно одного параметра amount — суммы счёта в долларах США (строка или число, максимум 2 знака после точки):

curl -X POST https://app.grampaybot.com/api/createInvoice \
  -H 'GramPay-API-Token: gp_live_xxx' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order_184' \
  -d '{
    "amount": "10.00",
    "public_description": "Доступ на 30 дней",
    "internal_note": "Клиент A",
    "payload": "order_123"
  }'

Разница между тремя текстовыми полями важна:

• public_description — видит покупатель на странице оплаты (легаси-алиас: description);
• internal_note — приватная заметка продавца, до 160 символов, покупателю не показывается;
• payload — машиночитаемые данные вашей системы (например, ID заказа); возвращаются в API-ответах и webhooks, по ним можно искать счёт.

Заголовок Idempotency-Key необязателен, но рекомендуем его для защиты от дублей — подробности в справочнике API.

Ответ и две ссылки на оплату

В result приходит объект счёта. Ключевые поля для старта:

{
  "ok": true,
  "result": {
    "public_id": "GU91XHr8AUNQ8l9r",
    "status": "active",
    "amount_usd": "10.00",
    "payload": "order_123",
    "web_app_invoice_url": "https://app.grampaybot.com/invoices/GU91XHr8AUNQ8l9r",
    "bot_invoice_url": "https://t.me/GramPayBot?start=pay_GU91XHr8AUNQ8l9r"
  }
}

Покупателю можно отправить любую из двух ссылок:

• web_app_invoice_url — hosted checkout в браузере: сумма, выбор сети, адрес, QR-код и живой статус;
• bot_invoice_url — открывает счёт в GramPayBot; кнопка оплаты ведёт в тот же счёт внутри Telegram Mini App.

Обе страницы используют язык, настроенный в проекте продавца.

Проверка подключения: getMe

Самый простой способ убедиться, что токен работает:

curl https://app.grampaybot.com/api/getMe \
  -H 'GramPay-API-Token: gp_live_xxx'

{ "ok": true, "result": { "app_id": "6d86f4e0-6ad2-4fb9-9f0c-f2eb9ab5c4c7", "name": "My Shop", "status": "active" } }

app_id — UUID приложения, а не последовательный числовой ID.

Что дальше

Статус счёта можно опрашивать через getInvoice, но правильный путь — подключить webhooks: GramPayBot сам пришлёт invoice_paid с суммой, токеном, сетью и tx_hash, когда оплата подтвердится в блокчейне. Полное описание методов — в справочнике API, готовые фрагменты кода — в примерах интеграции.