Бот ведёт заказ, деньги принимает касса продавца
В этом сценарии 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 достаточно технической метки канала; привязка покупателя остаётся в вашей БД.
curl -fsS https://bankemes.kz/sdk/bankemes-node.mjs -o bankemes.mjsimport { 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.