Платный Telegram-канал с оплатой через Kaspi: как это устроить
Ежемесячный счёт в Kaspi, напоминания и долг ведёт KazPayment, доступ в канал выдаёт ваш бот по вебхуку. Какие ручки API и события нужны.
Короткий ответ. KazPayment берёт на себя деньги: каждый месяц выставляет
подписчику счёт в Kaspi, напоминает об оплате, ведёт долг и знает, до какого
дня оплачено. Пускать в канал и удалять из него должен ваш собственный
Telegram-бот: готовой связки с Telegram-каналом в KazPayment нет. Бот узнаёт
об оплате из вебхука payment.received, в котором есть поле paid_until, а об
отмене подписки из события subscription.cancelled. Для проверки в любой
момент есть GET /api/v1/subscriptions.
Кто что делает
Сразу о границе, чтобы не было сюрпризов. KazPayment не администратор вашего канала. Он не создаёт ссылки-приглашения и никого из канала не удаляет.
| Задача | Кто делает |
|---|---|
| Счёт в Kaspi каждый период | KazPayment |
| Напоминания: до срока, в срок, после | KazPayment |
| Долг, отмена за неоплату | KazPayment, по вашему правилу |
| «Оплачено до такого-то дня» | KazPayment, поле paid_until |
| Впустить в канал, удалить из канала | ваш бот |
| Связать человека в Telegram с подпиской | ваш бот |
Деньги идут прямо на ваш счёт в Kaspi. Комиссию за приём, 0,95%, удерживает сам Kaspi. KazPayment деньги не хранит и не переводит.
Схема по шагам
Понадобится ключ интеграции и адрес для вебхука. Как их получить, описано в инструкции Подключить интернет-магазин или телеграм-бот. Все ручки и поля — в документации API.
1. Заведите тариф в кабинете. «Клиенты и подписки» → «Тарифы», режим
«Подписка». Через API тариф не создать, это сделано намеренно: цену решает
владелец, а не программа. Боту хватит GET /api/v1/plans, чтобы узнать id
тарифа.
2. Бот спрашивает номер телефона. Счёт в Kaspi приходит на номер, поэтому без телефона подписку не оформить.
3. Бот заводит клиента и подписку. Сначала POST /api/v1/payers с телефоном
и именем, потом POST /api/v1/subscriptions с payer_phone и plan_id.
Повтор безопасен: тот же номер вернёт того же клиента, а тот же клиент с тем же
тарифом вернёт действующую подписку, второй не появится. В ответе придёт id
подписки. Сохраните у себя пару «человек в Telegram ↔ subscription_id».
Это важно: в событиях KazPayment нет ни имени, ни телефона, только
идентификаторы и суммы.
4. Подписчик платит. Счёт приходит ему в приложение Kaspi, напоминания уходят по вашим сценариям, со ссылкой на страницу оплаты. На странице можно заплатить и QR-кодом из другого банка (Оплата по ссылке и QR).
5. Бот получает payment.received. У оплаты подписки order_ref пустой, а
subscription_id и payer_id заполнены. Поле paid_until — последний
оплаченный день с учётом этой оплаты. Бот находит человека по
subscription_id, впускает его в канал и запоминает дату.
6. Бот сам следит за датой. Отдельного события «срок истёк» нет. Если
подписчик не заплатил, подписка может оставаться активной и копить долг, а
paid_until просто остаётся в прошлом. Поэтому раз в день бот проверяет: у
кого paid_until раньше сегодняшнего дня, того удаляет из канала.
7. Бот получает subscription.cancelled. Оно приходит, кто бы ни отменил
подписку: ваш бот через PUT /api/v1/subscriptions/<id>, вы в кабинете или
правило неоплаты. В событии тоже есть paid_until. Отменили посреди
оплаченного месяца, значит доступ честно остаётся до этой даты.
Календарный месяц или «30 дней от оплаты»
У тарифа-подписки два вида периода, и для канала это важный выбор.
По календарю. Счёт приходит в одно и то же число, например 1-го. Кто вступил 20-го, получит первый счёт в день начала подписки. Сколько он платит за неполный месяц, решаете вы: полную сумму или за оставшиеся дни.
От дня оплаты. Каждые 7, 30, 90 или 365 дней. Следующий счёт приходит, когда закончится оплаченный период. Заплатил человек с опозданием, отсчёт идёт от дня оплаты, и дни просрочки оплаченные дни не съедают. Для канала и клуба это обычно честнее: купил доступ 20-го, пользуется до 19-го следующего месяца.
Считать даты у себя не нужно. paid_until уже учитывает и календарь, и
опоздание, и долг.
Что делать с теми, кто не платит
Внизу раздела «Тарифы» есть правило «Если клиент не оплатил подписку». То же
правило доступно через GET и PUT /api/v1/settings/unpaid-policy. Вариантов
четыре:
- Копить долг отдельными счетами (
debt, по умолчанию). Подписка действует, напоминания идут. - Добавлять долг в следующий счёт (
merge). Неоплаченное входит в счёт следующего периода одной суммой. - Не считать пропущенное долгом (
forgive). Через заданное число дней неоплаченный счёт закрывается. Работает на календарных тарифах. - Отменять подписку (
cancel). Через заданное число дней подписка отменяется сама, и бот получаетsubscription.cancelled.
Для канала проще всего cancel: не заплатил, значит ушёл. Бот удаляет человека
по событию или по дате.
У тарифа «от оплаты» в режиме merge счёт растёт: 1 500 → 3 000 → 4 500 ₸.
Сколько периодов копить, задаётся от 1 до 24, по умолчанию 3. Когда предел
набран и со срока счёта прошёл ещё один период, подписка отменяется сама.
Если человек всё же оплатит выросший счёт, доступ продлится на один период от
дня оплаты, а не на все накопленные. Учтите это, если ставите такой режим
каналу: человек платит за месяцы, когда доступа у него не было.
О чём легко забыть
- Проверяйте подпись. Каждое событие подписано заголовком
X-Kazpayment-Signature. Без проверки любой, кто узнал адрес, пришлёт вам «оплату». - Одно событие может прийти дважды. Повтор несёт тот же
event_id. Храните обработанные и не выдавайте доступ второй раз. - Смотрите на поле
event. Событий несколько, и решать по одному толькоsubscription_idнельзя. - Вебхук может не дойти. Если бот лежал полтора суток, доставка
прекратится. Недоставленное можно дослать через
POST /api/v1/webhook/resend, а сверяться сpaid_untilвGET /api/v1/subscriptions. - Пауза события не даёт. Поставили подписку на паузу в кабинете, бот об
этом не узнает. Статус виден только в
GET. - Оплата видна не мгновенно. Её подтверждает выписка кассы, обычно за несколько минут.
- Счета нового бизнеса стоят на паузе, пока вы не нажмёте «Начать выставлять
счета». Через API это
POST /api/v1/settings/auto-billing/start. - Переезжаете с другого сервиса? Передайте
paid_untilпри оформлении подписки, и уже заплатившие не заплатят второй раз.
Напоминания и бот поддержки
Напоминания KazPayment отправляет сам. Если подписчик подключил Telegram по
ссылке-приглашению, напоминание уходит туда бесплатно. Ссылку выпускают в
разделе «Клиенты», а ваш бот может получить её сам запросом
POST /api/v1/payers/<id>/telegram-link и сразу прислать подписчику.
Иначе в WhatsApp за 18 ₸ или SMS за 30 ₸ с вашего баланса. Это бот
KazPayment, а не ваш, и к доступу в канал он отношения не имеет. Подробно:
Напоминания об оплате.
В WhatsApp можно включить автоответчик. Он отвечает подписчикам на «сколько я должен», «пришлите ссылку», «я оплатил» и зовёт вас, если не понял вопрос. Отвечает он только тем, кто уже есть у вас в базе: человеку «с улицы» он не напишет ничего, и записывать в канал он не умеет (Автоответчик в WhatsApp).
Сколько стоит
API и вебхуки есть на любом тарифе, включая Free: до 100 оплат за 30 дней бесплатно. Дальше «Мини» за 4 490 ₸ за 1 200 оплат. В лимит идут только оплаченные счета. Платные сообщения списываются с баланса отдельно, а напоминания в Telegram бесплатны.
Частые вопросы
KazPayment сам добавляет и удаляет людей из Telegram-канала?
Нет. Готовой связки с Telegram-каналом нет. KazPayment выставляет счета, напоминает и сообщает вашему боту об оплате и отмене через вебхук, а впускает и удаляет участников ваш собственный бот.
Откуда бот узнаёт, до какого дня человек заплатил?
Из поля paid_until в вебхуке payment.received. Это последний оплаченный
день с учётом этой оплаты. Та же дата есть в ответе GET /api/v1/subscriptions
и в событии subscription.cancelled.
Приходит ли событие, когда оплаченный срок закончился?
Нет. Приходят события об оплате и об отмене подписки. Если подписчик просто не
заплатил, подписка может оставаться активной с долгом, поэтому бот раз в день
сам удаляет тех, у кого paid_until уже в прошлом.
Можно брать плату ровно за 30 дней с момента оплаты?
Да. Выберите у тарифа период «от дня оплаты», 30 дней. Следующий счёт придёт, когда закончится оплаченный период, а при оплате с опозданием отсчёт начнётся со дня оплаты.
Что будет, если подписчик не платит несколько месяцев?
Решает правило неоплаты: копить долг, добавлять его в следующий счёт, прощать
пропуск или отменять подписку через заданное число дней. При отмене бот
получает subscription.cancelled и удаляет человека из канала.
Нужен ли подписчику Kaspi?
Счёт приходит в приложение Kaspi на его номер. Без Kaspi можно заплатить на странице оплаты по QR-коду, его понимают приложения других банков. Ссылка на страницу приходит в напоминаниях.
Попробуйте KazPayment бесплатно
Тестовый режим без ограничения по времени: заведите тарифы, товары и счета и посмотрите, как это работает, до того как подключать настоящую кассу.
Начать бесплатно