Перейти к содержимому

Оплата через Telegram-бота: внешняя ссылка Bankemes

Как сервер бота создаёт платёж, связывает заказ с пользователем и подтверждает оплату через webhook. Внешний checkout и его отличие от Telegram Stars.

Команда Bankemes · Обновлено

Бот ведёт заказ, деньги принимает касса продавца

В этом сценарии Telegram-бот отправляет обычную URL-кнопку на страницу Bankemes. Сервер создаёт платёж, покупатель открывает checkout_url, а ваш backend получает результат по webhook. Деньги не хранятся у бота: платёж идёт через подключённую кассу продавца. Это внешняя страница оплаты, а не нативный Telegram invoice и не Telegram Stars.

Выберите сценарий, допустимый для вашего товара: например, оформление физического заказа или офлайн-услуги. Для цифровых товаров и услуг внутри Telegram действуют отдельные правила: Telegram требует Stars с валютой XTR. Внешняя Kaspi-ссылка не заменяет этот механизм. Границы применения описаны в документации Telegram.

Подготовьте зарегистрированный ресурс приложения, подключённую кассу и токен этого ресурса. Токен Bankemes и токен бота храните только на сервере. В чат, HTML, Mini App и адрес кнопки передаётся только публичный checkout_url, без Bearer-токена. Пример ниже использует ваш уже существующий bot adapter; Bankemes SDK не создаёт и не хостит Telegram-бота.

Создайте заказ до запроса платежа

Подлинность входящих данных Telegram проверяет ваш бот-сервер. Нельзя доверять user id, сумме или номеру заказа из произвольного клиентского JSON; сначала установите пользователя, затем разрешайте действие над его заказом.

На сервере свяжите внутренний order_id с Telegram user id, chat id, товаром и суммой. Имя пользователя может измениться; название чата не является владельцем заказа. Сумму берите из своего каталога, а не из callback_data или сообщения покупателя. Когда пользователь запрашивает статус, сверяйте его Telegram identity с владельцем сохранённого заказа.

Сохраните стабильный Idempotency-Key вместе с заказом перед первым запросом. payments.create возвращает id и checkout_url; сохраните id рядом с заказом до отправки кнопки. Повторный клик и повтор после таймаута должны использовать тот же заказ, тело и ключ. В metadata достаточно технической метки канала; привязка покупателя остаётся в вашей БД.

Shell
curl -fsS https://bankemes.kz/sdk/bankemes-node.mjs -o bankemes.mjs
Node.js
import { Bankemes } from './bankemes.mjs';
const bankemes = new Bankemes({ token: process.env.BANKEMES_API_TOKEN });

// order is a server-side record owned by the authenticated Telegram user.
// orders and bot are YOUR database and bot-library adapters, not SDK methods.
export async function sendOrderCheckout(order, orders, bot) {
  const payment = await bankemes.payments.create({
    order_id: order.id,
    amount: order.amountKzt,
    description: order.description,
    metadata: { channel: 'telegram' },
  }, { idempotencyKey: order.bankemesIdempotencyKey });

  await orders.bindPayment(order.id, payment.id);
  await bot.sendMessage(order.chatId, 'Checkout', {
    reply_markup: { inline_keyboard: [
      [{ text: 'Open payment page', url: payment.checkout_url }],
    ] },
  });
}

Выдавайте результат по проверенному webhook

Кнопка «Я оплатил» может запустить чтение статуса, но не выдачу заказа. Примите payment.paid на отдельном серверном endpoint: проверьте подпись исходного тела, сохраните event.id и перечитайте payment_id через API. Сравните оплаченный заказ, точную сумму amount_tiyn, KZT и livemode с серверной записью. Затем один раз подтвердите заказ или откройте предусмотренный вашим продуктом доступ.

Адресат подтверждения берётся из сохранённой связи заказа с пользователем. Если ссылка была переслана или сообщение бота удалено, связь не меняется. Подтверждение оплаты и будущая отправка сообщения должны переживать перезапуск сервера: используйте транзакцию и очередь. Ошибка Telegram при отправке уведомления не означает, что платёж не состоялся; повторяйте сообщение, а не списание.

Если нужен Kaspi-счёт на телефон, это отдельный remoteInvoices.create: у него нет checkout_url и нет режима bms_test. Обычный checkout из примера проверяйте тестовым токеном с livemode=false. Расписание счетов не является автоматическим списанием. Подробности: удалённые счета, регулярные счета, проверка webhook.

Проверки сценария бота

  • Двойной клик создаёт один платёж; перезапуск не меняет Idempotency-Key.
  • Чужой Telegram user id не читает и не меняет заказ покупателя.
  • Закрытый checkout и неподтверждённое expired оставляют заказ на проверке.
  • Повторный webhook не повторяет выдачу; тестовая оплата не выдаёт реальный заказ.
  • Сбой отправки сообщения повторяет уведомление без нового платежа.

Контракт запросов: Merchant API. Начальная настройка сервера: Quickstart. Поведение при неизвестном результате: статусы платежей.

Вопросы по теме

Это встроенная оплата Telegram?
Нет. Бот отправляет URL-кнопку на внешнюю страницу Bankemes. Здесь не используются Telegram sendInvoice, provider_token или Stars; правила цифровых товаров Telegram сохраняются.
Можно отправить API-токен в Mini App?
Нет. Mini App обращается к вашему backend, который проверяет пользователя и создаёт платёж. Клиенту возвращайте checkout_url, а не серверный секрет.
Кому выдать заказ, если ссылку переслали?
Пользователю, с которым ваш сервер связал заказ до создания платежа. URL оплаты не должен переназначать владельца заказа или открывать чужие данные.
Нужно делать новый платёж, если бот не прислал ответ?
Сначала прочитайте сохранённый платёж и очередь сообщений. Ошибка доставки в Telegram не доказывает неоплату. При неизвестном результате API используйте прежний Idempotency-Key.

Следующий шаг