Руководства → Подключить интернет-магазин или телеграм-бот

Подключить интернет-магазин или телеграм-бот

Эта статья — маршрут от нуля до первой оплаты: что за чем делать и как проверять себя на каждом шаге. Точный контракт (все поля, коды ошибок, лимиты) — в документации API.

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

Шаг 1. Аккаунт и режим

Зарегистрируйте бизнес на kazpayment.kz. Пока вы в тестовом режиме, касса поддельная: заказы создаются, страница оплаты открывается, но денег не принимает — оплату вы отмечаете сами из кабинета. Для отладки интеграции это удобнее настоящих денег.

Настоящий приём оплат включается оплатой тарифа и подключением кассы — см. Тестовый режим и Подключить кассу.

Шаг 2. Ключ интеграции

Ключ выдаём вручную: напишите на support@kazpayment.kz с адресом сайта или именем бота.

Ключ — это доступ к деньгам вашего бизнеса. Держите его в переменных окружения, не в коде и не в репозитории. Ключ интеграции не пускает в панель, а вход владельца не работает с API — это разные роли намеренно.

Проверьте ключ сразу:

curl -s https://kazpayment.kz/api/v1/whoami \
  -H "Authorization: Bearer $KAZPAYMENT_KEY"

Ответ 200 с "role": "integration" означает, что ключ рабочий. 401 — дело в самом ключе, дальше можно не искать.

Шаг 3. Заказ

Ваша система создаёт заказ и получает pay_url:

curl -s -X POST https://kazpayment.kz/api/v1/orders \
  -H "Authorization: Bearer $KAZPAYMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"external_ref":"SHOP-1042","amount":4500,"comment":"Пицца Маргарита"}'

Три вещи, которые стоит понять сразу:

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

Сумма фиксируется. Повтор с тем же номером, но другой суммой — ошибка, а не тихая замена. Передумали — новый заказ с новым номером.

customer_phone необязателен. Указали — клиенту дополнительно придёт счёт в приложение Kaspi. Не указали — заказ оплачивается только по ссылке.

Дальше отправьте покупателя на pay_url (редиректом или встроив страницу в iframe).

Шаг 4. Вебхук об оплате

Настройте адрес приёмника:

curl -s -X PUT https://kazpayment.kz/api/v1/webhook \
  -H "Authorization: Bearer $KAZPAYMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://shop.kz/kazpayment/hook"}'

В ответ придёт секрет — он показывается один раз, сохраните его сразу. Повторная настройка выпускает новый секрет (так делается ротация).

Ваш обработчик обязан:

  1. Проверить подпись X-Kazpayment-Signature по сырым байтам тела до разбора JSON. Без этого прислать вам «оплату» сможет кто угодно: адрес приёмника — не секрет.
  2. Ответить 2xx за 10 секунд. Тело ответа мы не читаем. Долгую работу делайте после ответа, а не до.
  3. Отбрасывать повторы по event_id. Доставка гарантируется «хотя бы однажды», поэтому одно и то же событие может прийти дважды — закрывайте сделку один раз.

Проверьте приёмник, не дожидаясь настоящей оплаты:

curl -s -X POST https://kazpayment.kz/api/v1/webhook/test \
  -H "Authorization: Bearer $KAZPAYMENT_KEY"

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

Шаг 5. Проверка на живых деньгах

Когда кабинет боевой и касса подключена, проведите одну маленькую оплату самому себе — например, на 100 ₸, и верните её из кабинета (Возврат). Это единственный способ убедиться, что всё сходится: заказ, оплата, вебхук, учёт.

Чего не делать

Не полагайтесь на вебхук как на единственный источник правды. Если ваш приёмник лежал полтора суток, событие не дойдёт вовсе. Статус заказа всегда можно спросить: GET /api/v1/orders/<ваш_номер>.

Не опрашивайте статус чаще раза в минуту — деньги подтверждаются по выписке кассы, и чаще она не обновляется. Действует ограничение частоты запросов; при его превышении вернётся 429.

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

Что делать, если хочется быстрее

Отдайте своему ИИ-ассистенту готовый промпт со страницы промптов — он прочитает машиночитаемую документацию (/docs/api.md) и напишет и создание заказа, и приёмник вебхука под ваш стек.

Не помогло? Напишите на support@kazpayment.kz — отвечает разработчик сервиса.