Справочник API

Шесть методов покрывают весь жизненный цикл счёта. Все запросы авторизуются заголовком GramPay-API-Token, все ответы завёрнуты в { "ok": …, "result": … } либо { "ok": false, "error": { "code", "message" } }.

Авторизация и права токена

Токен привязан к проекту и имеет набор прав (scopes): чтение счетов, создание, отмена, чтение статистики. Если у токена нет нужного права, метод вернёт 403:

{ "ok": false, "error": { "code": "FORBIDDEN", "message": "Token scope is not allowed" } }

Неверный или отсутствующий токен — 401 UNAUTHORIZED.

GET /api/getMe

Проверка токена и данных проекта. Параметров нет.

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

POST /api/createInvoice

Создаёт счёт. Параметры:

Параметр	Тип	Обязателен	Описание
amount	string | number	да	Сумма в USD, > 0, максимум 2 знака после точки. Запятая как разделитель допустима
public_description	string	нет	Назначение платежа, видит покупатель. Алиас: description
internal_note	string	нет	Приватная заметка продавца, до 160 символов
payload	string	нет	Машиночитаемые данные вашей системы; возвращаются в API и webhooks
expires_in	integer	нет	Срок жизни счёта в секундах, от 60 до 86 400
paid_btn_name	string	нет	Название кнопки после оплаты
paid_btn_url	string	нет	Ссылка кнопки после оплаты

Успех — объект счёта (см. «Структура invoice» ниже).

Идемпотентность

Передайте заголовок Idempotency-Key, чтобы повтор запроса (таймаут, retry) не создал второй счёт:

• ключ: 1–128 символов из букв, цифр, -, _, ., :; иначе 400 INVALID_IDEMPOTENCY_KEY;
• повтор с теми же нормализованными параметрами возвращает исходный счёт и заголовок ответа Idempotent-Replayed: true;
• тот же ключ с другими параметрами — 409 IDEMPOTENCY_KEY_REUSED;
• ключ действует в рамках проекта и переживает смену API-токена.

Не используйте payload как замену идемпотентности и не кладите в ключ секреты или персональные данные.

Ошибки createInvoice

HTTP	Код	Когда
422	INVALID_AMOUNT	Сумма не положительная или больше 2 знаков после точки
422	INVALID_PARAMS	Прочие невалидные параметры (в т.ч. expires_in вне 60–86 400)
422	ROUTE_NOT_AVAILABLE	В проекте нет настроенного платёжного маршрута (кошелёк + сеть)
402	account_not_serviceable	Кончился processing credit и нет активного пакета. Ответ содержит блок billing с балансом и остатками пакета
400	INVALID_IDEMPOTENCY_KEY	Неверный формат ключа
409	IDEMPOTENCY_KEY_REUSED	Ключ уже использован с другими параметрами

Обратите внимание: ответ 402 имеет отдельную форму — { "error": "account_not_serviceable", "message": …, "billing": { … } }.

GET /api/getInvoice

Возвращает один счёт. Ищет по одному из параметров (в порядке приоритета):

curl 'https://app.grampaybot.com/api/getInvoice?payload=order_123' -H 'GramPay-API-Token: gp_live_xxx'
curl 'https://app.grampaybot.com/api/getInvoice?public_id=GU91XHr8AUNQ8l9r' -H 'GramPay-API-Token: gp_live_xxx'
curl 'https://app.grampaybot.com/api/getInvoice?hash=GU91XHr8AUNQ8l9r' -H 'GramPay-API-Token: gp_live_xxx'

payload имеет приоритет над public_id / hash / id. Если счёт не найден — 404 INVOICE_NOT_FOUND.

GET /api/getInvoices

Постраничный список счетов проекта, новые сверху. Параметры:

Параметр	Описание
page	Номер страницы, с 1. Размер страницы фиксированный — 50
status	active (синоним waiting), paid, expired, cancelled. Другие значения игнорируются
public_ids	Фильтр по списку public_id

{
  "ok": true,
  "result": {
    "total_count": 132,
    "per_page": 50,
    "total_pages": 3,
    "current_page": 1,
    "items": [ { …invoice… } ]
  }
}

POST /api/cancelInvoice

Отменяет активный счёт. Алиас с тем же поведением: deleteInvoice.

curl -X POST https://app.grampaybot.com/api/cancelInvoice \
  -H 'GramPay-API-Token: gp_live_xxx' \
  -H 'Content-Type: application/json' \
  -d '{"public_id": "GU91XHr8AUNQ8l9r"}'

Если счёт уже оплачен, истёк или отменён — 409 INVALID_STATUS. Возвращает обновлённый объект счёта.

GET /api/getStats

Статистика по счетам проекта за период. Параметр period: today, yesterday, week, month, previous_month, last_30_days, all_time (по умолчанию — all_time).

{
  "ok": true,
  "result": {
    "volume": "1240.50",
    "created_invoice_count": 87,
    "paid_invoice_count": 61,
    "conversion": "0.7",
    "average_paid_invoice": "20.34",
    "start_at": "2026-07-01T00:00:00Z",
    "end_at": "2026-07-17T09:00:00Z"
  }
}

Структура invoice

Объект счёта одинаков во всех методах и внутри payload webhook-событий:

Поле	Описание
public_id, hash	Публичный идентификатор счёта (одно и то же значение)
status	active, paid, expired, cancelled
amount_usd	Сумма счёта в USD, строка с 2 знаками
amount_usdt, amount_usdc	Точные суммы к оплате в токенах (если маршрут доступен)
paid_token	Чем оплачен: usdt / usdc, до оплаты — null
paid_source	Источник оплаты
public_description	Публичное назначение платежа
internal_note	Приватная заметка продавца
payload	Ваши машиночитаемые данные
web_app_invoice_url	Ссылка на hosted checkout в браузере
bot_invoice_url	Ссылка на счёт в GramPayBot (Mini App)
tx_hash	Хэш транзакции оплаты, до оплаты — null
created_at, expiration_date	Создание и срок действия, ISO 8601
paid_at, cancelled_at	Момент оплаты / отмены, ISO 8601 или null
cancel_reason	Причина отмены

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