Процесс оплаты заказа

Прямая оплата через платёжную систему (карта, СБП и т.д.) с веб-страницы, Telegram Web App или мобильного приложения. Списание внутреннего баланса бота через эти методы не поддерживается.

Базовый URL: https://api.bot-t.com

Все методы — POST, тело JSON, заголовок Content-Type: application/json.

Авторизация

Не нужны: токен бота (token / botToken) и секретный ключ бота (secretKey).

Нужен доступ к заказу — одно из двух полей в теле каждого запроса:

Поле	Описание
`order_key` или `orderKey`	секретный ключ заказа из ответа создания заказа (поле `orderKey`). На страницу оплаты его обычно передают в query URL — см. ниже
`secret_user_key`	секрет пользователя бота — владельца заказа

Без ключа:

{ "result": false, "message": "not_access (public_pay_key)" }

Обязательные поля в каждом запросе

Поле	Тип	Описание
`bot_id`	integer	ID бота. Должен совпадать с ботом заказа
`order_id`	string	идентификатор оплаты (форматы ниже)
`order_key` / `orderKey` или `secret_user_key`	string	доступ к заказу; достаточно одного варианта

Откуда взять ключ

Тип `order_id`	`order_key` / `orderKey`	`secret_user_key`
`o-{id}`	поле `orderKey` из ответа создания заказа магазина	секрет владельца, если заказ привязан к пользователю
`c-{id}`	поле `orderKey` из ответа создания заказа корзины	секрет владельца заказа
`p-{id}`	поле `orderKey` из ответа создания истории оплаты сообщения; в кнопках URL — плейсхолдер `{ORDER_KEY}`	секрет плательщика (альтернатива)

Ключ привязан к типу заказа: ключ от c-123 не откроет o-123 или p-123.

Как ключ попадает на страницу оплаты

Создаёте заказ / запись оплаты через API.
В ответе сохраняете order_id (или собираете o-{id} / c-{id} / p-{id}) и строку orderKey.
Открываете свою страницу оплаты и передаёте туда параметры (часто в query URL), например:

https://example.com/pay?bot_id=1&order_id=o-123321&order_key=a1b2c3d4e5f6...

Имена параметров могут быть любыми на вашей стороне. Важно: при вызове API отправьте их как bot_id, order_id и order_key (или orderKey) в JSON-теле.

Тот же orderKey можно хранить в localStorage, сессии или QR — суть одна: клиент должен иметь секрет заказа до первого get-status.

Telegram deep-link вида https://t.me/{бот}?start=o_{id} содержит только номер заказа, без order_key. Для оплаты через этот публичный API его недостаточно: нужен сохранённый orderKey с шага создания или secret_user_key владельца.

Оплата сообщения (`p-{id}`)

При создании записи истории оплаты (API create-payment-history или отправка сообщения-оплаты в боте) в ответе / данных записи приходят:

Поле	Пример	Назначение
`order_id`	`p-44744`	идентификатор для `payment/order`
`orderKey`	`a1b2c3...`	секрет доступа (`order_key` в запросах оплаты)

Пример ответа создания:

{
  "result": true,
  "data": {
    "id": 44744,
    "order_id": "p-44744",
    "orderKey": "a1b2c3...",
    "status": "pending"
  }
}

Дальше — как у магазина:

https://example.com/pay?bot_id=51318&order_id=p-44744&order_key=a1b2c3...

{
  "bot_id": 51318,
  "order_id": "p-44744",
  "order_key": "a1b2c3..."
}

В тексте и URL кнопок сообщения-оплаты можно использовать плейсхолдеры {ORDER_ID} и {ORDER_KEY} — бот подставит p-{id} и секрет при отправке.

Альтернатива без order_key: передать secret_user_key пользователя, которому принадлежит платёж (Web App / API пользователя бота).

{
  "bot_id": 51318,
  "order_id": "p-44744",
  "secret_user_key": "k7f3a9b2c1d4e5f6"
}

Форматы `order_id`

Префикс	Что оплачивается	Пример
`o-`	заказ магазина	`o-123321`
`c-`	заказ корзины	`c-456`
`p-`	оплата сообщения бота	`p-789`

Формат ответа

{ "result": true, "data": ... }

{ "result": false, "message": "текст ошибки" }

Всегда проверяйте result === true перед использованием data.

Лимит: 120 запросов в минуту с одного IP.

Типовой сценарий

sequenceDiagram
    participant UI as Страница оплаты
    participant API as API оплаты

    UI->>API: get-status (bot_id, order_id, order_key)
    alt result=false (уже оплачен)
        UI->>UI: Экран «Заказ уже оплачен»
    else status=wait
        UI->>API: get-groups
        UI->>API: get-items
        UI->>API: get-pay-data
        UI->>UI: Редирект / форма оплаты
        UI->>API: check-pay или get-status
    end

Сценарий одинаков для o-, c- и p-. Ключ доступа (order_key или secret_user_key) передаётся во всех шагах.

Методы

Базовый путь: POST https://api.bot-t.com/v1/payment/order/{действие}

Действие	Назначение
`get-status`	статус: ожидает оплаты или уже оплачен
`get-groups`	группы способов оплаты
`get-items`	способы оплаты в группе (`group_id`)
`get-pay-data`	данные для экрана оплаты (`item_id`)
`set-pay-input`	ввод пользователя, когда нужен текст (тип оплаты 2)
`check-pay`	проверка оплаты у платёжной системы
`cancel`	отмена сценария

Примеры запросов

Статус заказа магазина

{
  "bot_id": 1,
  "order_id": "o-123321",
  "order_key": "a1b2c3..."
}

Допустимо поле orderKey вместо order_key.

Статус заказа корзины

{
  "bot_id": 1,
  "order_id": "c-456",
  "order_key": "a1b2c3..."
}

Статус оплаты сообщения — через order_key

{
  "bot_id": 1,
  "order_id": "p-789",
  "order_key": "a1b2c3..."
}

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

{
  "bot_id": 1,
  "order_id": "p-789",
  "secret_user_key": "k7f3a9b2c1d4e5f6"
}

Данные для оплаты

{
  "bot_id": 1,
  "order_id": "p-789",
  "order_key": "a1b2c3...",
  "item_id": 15
}

Сохранить ввод пользователя (тип оплаты 2)

{
  "bot_id": 1,
  "order_id": "c-456",
  "order_key": "a1b2c3...",
  "item_id": 15,
  "input_value": "текст от пользователя"
}

Поле `dataPay.type`

type	Что делать на клиенте
0	показать `dataPay.text`
1	открыть ссылку `dataPay.link`
2	поле ввода → `set-pay-input` → снова `get-pay-data`
3, 4, 8	`requires_telegram: true` — завершить оплату в Telegram-боте
6	открыть Web App (`dataPay.web_app`)
7, 9	способ с чеком на сайте недоступен — выберите другой

Сумма в полях amount — в минимальных единицах валюты (копейки). Для отображения делите на 100.

Статус заказа

Проверка выполняется во всех методах.

Если заказ уже оплачен (или больше не ждёт оплаты):

{ "result": false, "message": "Заказ уже оплачен" }

Повторно пройти сценарий оплаты для такого заказа нельзя — покажите пользователю экран успеха.

При успешном get-status заказ всегда в состоянии ожидания:

{
  "result": true,
  "data": {
    "status": "wait",
    "order_id": "o-123321",
    "amount": 150000
  }
}

Ошибки

Ситуация	Типичный `message`
Нет или неверный ключ доступа	`not_access (public_pay_key)`
Неверный формат `order_id`	Допустимы только o-{id}, c-{id} или p-{id}
Заказ не найден	not found
`bot_id` не совпадает с ботом заказа	not_access (public_bot)
Заказ уже оплачен	Заказ уже оплачен
Способ с чеком	текст про другой способ или оплату в Telegram

Связанные разделы

Оплата сообщения (p-{id}): все запросы — PaymentMessagePublic.md.
Создание заказа магазина (o-{id}) и получение orderKey — документация публичного магазина.
Создание заказа корзины (c-{id}) и получение orderKey — документация публичной корзины.