Блог · Опыт

Кейс: счёт после оказанной услуги через API KazPayment

Как онлайн-сервис оформления виз выставляет счёт после подачи заявки, даёт семье один счёт со скидкой и шлёт WhatsApp и SMS через API KazPayment.

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

Короткий ответ. Онлайн-сервис оформления виз работает на KazPayment через API. Клиент оформляет услугу в веб-чате, а счёт за работу получает только тогда, когда заявка уже подана: платит за сделанное, а не за обещание. Семья или группа, которая едет вместе, получает один счёт со скидкой по числу людей. Счёт, оплату, сообщения в WhatsApp и SMS сервис ведёт сам, без участия человека: всё это несколько запросов к API и один приёмник вебхука.

Задача

У сервиса нет кассира и нет менеджера, который выставляет счета. Клиент пишет в веб-чат, присылает документы и отвечает на вопросы анкеты, а дальше сервис заполняет и подаёт заявку сам. Подача может занять от минут до суток: многое зависит от стороннего сайта, куда уходит анкета.

Отсюда три требования к оплате:

Кабинет KazPayment здесь не подходит по простой причине: в этом бизнесе счёт выставляет не человек, а программа, по событию «заявка подана». Поэтому всё сделано через API.

Как устроено

1. Клиент оформляет услугу в чате. Нажимает «Всё верно, подать», и заявка встаёт в очередь. Счёта на этом шаге нет.

2. Заявка подана, выставляется счёт. Сервис заводит заказ в KazPayment (POST /api/v1/orders) и показывает ссылку на оплату в чате. Номером заказа служит публичный номер заявки: он не угадывается и не меняется. Если у клиента казахстанский телефон, он передаётся в customer_phone, и по заказу на одного человека сервис сразу просит KazPayment прислать ссылку на оплату в WhatsApp (POST /api/v1/orders/{номер}/notify).

3. Клиент платит. KazPayment присылает событие payment.received на адрес сервиса. Сервис проверяет подпись, закрывает счёт у себя и отдаёт клиенту то, что придерживал до оплаты.

4. Сервис сообщает о результате. Когда документ готов, клиенту уходит служебное сообщение в WhatsApp (POST /api/v1/whatsapp/order), а о сроках, за которыми надо следить, напоминание по SMS (POST /api/v1/sms).

Минимальный запрос на заказ выглядит так:

POST /api/v1/orders
Authorization: Bearer <ключ интеграции>

{"external_ref": "<номер заявки>", "amount": <сумма в тенге>,
 "comment": "Оформление визы", "customer_phone": "+7 7XX XXX XX XX"}

Семья и группа: один счёт, у каждого своя ссылка на сбор

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

Номер группового заказа строится не от одной из заявок, а от поездки, со случайным хвостом. Сначала номер зависел только от времени, и два счёта одной группы, заведённые в одну секунду, сталкивались на уникальном номере.

Если состав поездки меняется, прежний счёт снимается и заводится новый на новый состав. Счёт на часть группы не выдаётся за счёт на всех: заплатив по нему, клиент решил бы, что рассчитался за всех.

Кроме оплаты работы, у каждого человека в семье есть визовый сбор, и платится он не сервису, а на стороннем сайте. Для этого в notify передаётся адрес чужой оплаты в link и сумма в amount. KazPayment шлёт отдельный шаблон, где прямо сказано, что платят не нам, и считает «одно сообщение» на каждую ссылку. Поэтому заказ один на семью, а свою ссылку на сбор в WhatsApp получает каждый.

Сообщения: WhatsApp и SMS с одного баланса

Сервис пользуется тремя видами сообщений через API:

SMS сервис отправляет своим текстом: например, предупреждение о скором конце срока или о смене данных для входа. Текст держат коротким, потому что списывается каждая часть.

Все платные сообщения списываются с одного баланса бизнеса в KazPayment. Если сообщение не ушло, заявка от этого не ломается: ссылка всё равно есть в чате и в письме, а исход отправки записывается в историю заявки.

Если что-то сломалось

Вебхук не единственный источник правды. Повтор события для KazPayment норма, поэтому сервис запоминает event_id и второй раз счёт не закрывает. Событие может и не дойти, поэтому перед каждым напоминанием о неоплаченном счёте сервис спрашивает статус заказа (GET /api/v1/orders/{номер}). Сначала сверка только закрывала найденную оплату, а работа не начиналась. Теперь найденная оплата идёт тем же путём, что событие.

Сумма сверяется. Если в событии пришло меньше, чем в счёте, работа не начинается, а владельцу уходит тревога.

Повтор безопасен. Заказ идемпотентен по external_ref: повторный запрос с тем же номером возвращает уже заведённый заказ, а не второй. Если счёт не выставился, раз в минуту его ищет обход и пробует снова, а тревога владельцу приходит не чаще раза в 15 минут, чтобы не засыпать его сообщениями.

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

Сообщение семье не уходило. WhatsApp о сборе сервис отправлял по номеру заявки, а у семьи заказ общий. KazPayment такого заказа не находил и отвечал no_phone. Теперь сервис берёт номер того заказа, которым заявка оплачена.

Сбой не равен пропаже. Каждые 15 минут сервис сверяет оплаченные счета с KazPayment, чтобы увидеть возвраты и отмены. Однажды сверка попала на перезапуск, ответ 502 приняли за «счёта нет», и владелец получил ложную тревогу. Теперь «такого заказа нет» (404) и «не ответили» разделены: на второе сервис просто спросит снова.

Второй раз за ту же работу не берут. Клиент, у которого не прошла подача, удалял заявку и заводил новую, и ему выставляли новый счёт. Теперь оплата, оставшаяся без заявки, засчитывается новой заявке на тот же паспорт. А если клиент всё-таки оплатил старый счёт после смены состава семьи, владелец сразу узнаёт о двойной оплате и возвращает лишнее.

Сообщение не уходит дважды. Перед отправкой «документ готов» сервис ставит у себя отметку и снимает её только при явном отказе. Ответ мог потеряться уже после того, как сообщение ушло и деньги списались, и повтор отправил бы второе.

Что можно повторить у себя

Маршрут подключения по шагам есть в инструкции «Подключить интернет-магазин или телеграм-бот», а как собрать свой порядок шагов, в статье «Свой сценарий».

Частые вопросы

Почему счёт после услуги, а не предоплата?

Так клиент платит только за сделанную работу. Технически это ничем не сложнее: заказ в KazPayment заводится в любой момент одним запросом, и сервис делает это в момент подачи заявки, а то, что выдаётся после оплаты, просто придерживает до события payment.received.

Можно ли одним заказом оплатить работу за нескольких человек?

Да. Заказ один на семью или группу, сумму считаете вы. Если потом каждому нужна своя ссылка на оплату на стороннем сайте, notify с полем link отправит каждую по разу, подробнее в документации API.

Что если вебхук не дошёл?

KazPayment повторяет доставку около полутора суток, но полагаться только на неё не стоит. Спрашивайте GET /api/v1/orders/{номер} перед важным шагом, например перед напоминанием об оплате, и найденную оплату проводите тем же путём, что и событие.

Чем платятся WhatsApp и SMS?

С одного баланса бизнеса в KazPayment, общего для кабинета и API. Текущий остаток и цены отдаёт GET /api/v1/balance.

Можно ли напоминать о неоплаченном счёте через KazPayment?

Можно. Этот сервис напоминает сам, письмами по своему расписанию, а кабинет умеет слать напоминания по сценариям, см. «Как перестать вручную напоминать клиентам об оплате».

Попробуйте KazPayment бесплатно

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

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