Приём оплаты для Telegram-проектов: бот ведёт на сайт, оплата по СБП, картой и в криптовалюте

Как подключить оплату в Telegram-боте: схема с сайтом проекта

Сначала определите, где проходит продажа. Цифровые товары и услуги внутри бота Telegram продаёт за Stars, а на отдельном сайте проекта можно принимать СБП, банковские карты и криптовалюту через Paycryp. Бот хранит номер заказа и ведёт покупателя на сайт, а доступ выдаётся по подписанному вебхуку, а не по возврату пользователя в чат.

Платежи в Telegram-боте через сайт проекта проходят в пять шагов:

• Бот → заказ. Покупатель выбирает товар или тариф в боте. Ваш сервер создаёт заказ с собственным номером (orderId), привязывает его к Telegram-пользователю и сохраняет до отправки любых сообщений.
• Заказ → сайт проекта. Бот отправляет кнопку со ссылкой на страницу заказа на вашем сайте. В ссылке — только внутренний идентификатор заказа, без телефона, почты и токенов доступа.
• Сайт → счёт через API. Сервер сайта вызывает POST /v1/payments Merchant API с суммой и orderId, получает paymentUrl и перенаправляет покупателя на платёжную страницу Paycryp. Там покупатель сам выбирает СБП, банковскую карту или криптовалюту.
• Оплата → вебхук. После подтверждения оплаты Paycryp отправляет на Webhook URL терминала подписанное событие payment.confirmed. Сервер проверяет подпись, находит заказ по orderId и сверяет baseAmount и currency с ценой заказа.
• Вебхук → доступ в боте. Сервер помечает заказ оплаченным один раз и отправляет пользователю сообщение в бот: ключ, ссылку, файл или подтверждение подписки.

Возврат покупателя на successUrl и его появление в чате оплатой не считаются: источник истины — вебхук и контрольный запрос GET /v1/payments/order/{orderId}. Отгружайте заказ только по статусу CONFIRMED. Разбор ролей бота, статусов и сообщений покупателю — в статье как связать Telegram-бота с оплатой на сайте.

Где проходит продажа — какой способ оплаты

Правила Telegram различают покупки внутри платформы и покупки на внешнем сайте. От этого зависит, какая платёжная система для Telegram-бота нужна на каждом шаге пути покупателя. Paycryp не является провайдером Stars и оплату внутри бота или Mini App не подключает: его роль — приём оплаты по СБП, картой и в криптовалюте на сайте проекта. Требования Telegram к платежам описаны в документации для разработчиков ботов.

Если у проекта есть и бот, и сайт, нарисуйте два пути покупателя и не смешивайте их заказы: подробно — в статье Telegram Stars или оплата на сайте проекта.

Подписки и продления: рекуррентных списаний нет

Paycryp не делает автоматических списаний: покупатель каждый раз подтверждает оплату сам. Каждое продление подписки — новый счёт с новым orderId. Автопродление подписок в разработке.

Что это значит для бота:

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

Так же устроены подписки VPN-сервисов и SaaS: сценарии выдачи ключей, доступов и курсов разобраны на странице оплата цифровых товаров. Комиссия за приём и порядок выплаты в USDT — на странице тарифов.

Код: создать счёт и обработать вебхук

Примеры учебные: суммы условные, обработка ошибок опущена. Ключ терминала pk_live_… и секрет подписи whsec_… хранятся только на сервере, в переменных окружения; в код Mini App или в браузер они не попадают. Суммы передаются в минорных единицах валюты терминала.

Создание счёта на сервере сайта

import os, requests

API = "https://api.paycryp.app/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['PAYCRYP_KEY']}"}

def create_payment(order):
    # 49000 = 490,00 ₽ — учебная сумма в минорных единицах
    resp = requests.post(f"{API}/payments", headers=HEADERS, json={
        "amount": order.amount_minor,
        "orderId": order.id,                    # ключ идемпотентности
        "description": f"Заказ {order.id}",
        "metadata": {"tgUserId": str(order.tg_user_id)},
        "successUrl": f"https://shop.example/orders/{order.id}",
    }, timeout=10)
    resp.raise_for_status()
    return resp.json()["paymentUrl"]           # сюда перенаправляем покупателя

Повторный POST /v1/payments с тем же orderId и той же суммой вернёт уже созданный счёт, а не второй: если покупатель нажал «Купить» дважды, бот ведёт его на ту же платёжную страницу.

Обработка вебхука и выдача доступа в боте

import hmac, hashlib, os
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = os.environ["PAYCRYP_WEBHOOK_SECRET"]
# Заголовки подписи и идентификатора доставки — как в документации Merchant API
SIGNATURE_HEADER = "X-Paycrypt-Signature"
DELIVERY_HEADER = "X-Paycrypt-Delivery"

def signature_ok(header, raw_body):
    parts = dict(p.split("=", 1) for p in header.split(","))
    expected = hmac.new(SECRET.encode(), f"{parts['t']}.".encode() + raw_body,
                        hashlib.sha256).hexdigest()
    return hmac.compare_digest(parts.get("v1", ""), expected)

@app.post("/webhooks/paycryp")
def webhook():
    raw = request.get_data()                    # тело до разбора JSON
    if not signature_ok(request.headers[SIGNATURE_HEADER], raw):
        abort(400)
    if already_processed(request.headers[DELIVERY_HEADER]):
        return "", 200                          # повтор доставки
    event = request.get_json()
    p = event["payment"]
    if event["event"] == "payment.confirmed":
        order = find_order(p["orderId"])
        if order and p["baseAmount"] == order.amount_minor and p["currency"] == order.currency:
            mark_paid_once(order, p["id"])      # один платёж — одна выдача
            send_access_to_bot(order.tg_user_id)
    return "", 200

Подпись считается по секрету и исходному телу запроса, идентификатор доставки при повторах не меняется — по нему события дедуплицируются. Сервер отвечает кодом 2xx за 10 секунд, иначе событие придёт повторно; долгую выдачу лучше отделить от приёма события. Поле version показывает время изменения платежа — применяйте только событие новее последнего обработанного. Полное описание полей, событий и повторов — в документации Merchant API, разбор проверки — в статье вебхук оплаты.

Типичные ошибки при приёме оплаты в Telegram-боте

Эти ошибки чаще всего встречаются в ботах приёма платежей, и все они проверяются до запуска.

• Потерянный orderId. Бот создаёт новый номер при каждом нажатии «Купить» или не сохраняет заказ до отправки ссылки. Вебхук приходит с номером, которого нет в базе, и оплаченный заказ повисает без выдачи. Решение: заказ сохраняется до ссылки, повторное нажатие возвращает тот же orderId. Подробнее — в статье повторный запрос и двойная оплата.
• Двойная выдача. Вебхук доставлен повторно или обработчик запущен дважды, и пользователь получает два ключа или два периода подписки. Решение: дедупликация по идентификатору доставки и отметка «выдано» по идентификатору платежа, которую проверяют перед каждой выдачей.
• Выдача по возврату в чат. Бот считает заказ оплаченным, когда пользователь нажал «Я оплатил» или вернулся по successUrl. Решение: доступ открывается только по статусу CONFIRMED из подписанного вебхука или ответа GET.
• Ключ терминала в Mini App. Ключ или секрет подписи попал в код, который выполняется у покупателя. Решение: счёт создаёт только сервер, а при утечке ключ перевыпускают в кабинете — старый перестаёт работать сразу.
• Истёкший счёт. Срок счёта задаётся в настройках терминала (по умолчанию 30 минут). Если покупатель вернулся позже, бот создаёт новый заказ с новым orderId, а не продлевает старый. При этом уже начатая оплата может подтвердиться после EXPIRED — принимайте поздний payment.confirmed и сверяйте статус через GET.

Для кого эта страница

Страница написана для владельцев и разработчиков Telegram-проектов: ботов, каналов и Mini App, у которых есть или планируется сайт. Подключиться может любой: компания, ИП или частное лицо; стандартное подключение проходит онлайн, без паспортной анкеты и бумажного договора.

Если вы покупатель и оплатили заказ в чужом боте, а доступ не пришёл, обращайтесь в поддержку этого проекта: Paycryp не является стороной сделки и товары не выдаёт. Что сообщить продавцу и как проверить статус — в статье оплата прошла, заказ не подтвердился.