Блог · Как устроено

Платный Telegram-канал с оплатой через Kaspi: как это устроить

Ежемесячный счёт в Kaspi, напоминания и долг ведёт KazPayment, доступ в канал выдаёт ваш бот по вебхуку. Какие ручки API и события нужны.

18 ноября 20267 мин чтения0 прочтений

Короткий ответ. 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. Вариантов четыре:

Для канала проще всего cancel: не заплатил, значит ушёл. Бот удаляет человека по событию или по дате.

У тарифа «от оплаты» в режиме merge счёт растёт: 1 500 → 3 000 → 4 500 ₸. Сколько периодов копить, задаётся от 1 до 24, по умолчанию 3. Когда предел набран и со срока счёта прошёл ещё один период, подписка отменяется сама. Если человек всё же оплатит выросший счёт, доступ продлится на один период от дня оплаты, а не на все накопленные. Учтите это, если ставите такой режим каналу: человек платит за месяцы, когда доступа у него не было.

О чём легко забыть

Напоминания и бот поддержки

Напоминания 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 бесплатно

Тестовый режим без ограничения по времени: заведите тарифы, товары и счета и посмотрите, как это работает, до того как подключать настоящую кассу.

Начать бесплатно