Руководства → Подключить интернет-магазин или телеграм-бот
Подключить интернет-магазин или телеграм-бот
Эта статья — маршрут от нуля до первой оплаты: что за чем делать и как проверять себя на каждом шаге. Точный контракт (все поля, коды ошибок, лимиты) — в документации API.
Схема простая: ваша система создаёт заказ и получает ссылку на оплату, покупатель платит по QR из приложения любого банка, а о поступлении денег вы узнаёте из вебхука.
Шаг 1. Аккаунт и режим
Зарегистрируйте бизнес на kazpayment.kz: он сразу работает на бесплатном тарифе Free, настоящий приём оплат включается подключением кассы — см. Подключить кассу.
Отлаживать интеграцию удобнее в песочнице — копии бизнеса без денег:
«Подключения» → «Интеграция» → «Песочница для разработчиков». Там свои ключи
(начинаются с kp_test_), заказы создаются, страница оплаты открывается, а
оплату, отказ или чужую сумму вы нажимаете сами прямо на ней. Сообщения из
песочницы уходят только вам. Подробно — в документации
API.
API и вебхуки работают на любом тарифе, включая бесплатный Free. На Free через API можно создать до 500 заказов за 30 дней (и до 100 оплат — как у всего тарифа); дальше нужен «Мини» или старше. В песочнице предела нет — отлаживайте интеграцию спокойно.
Шаг 2. Ключ интеграции
Ключ выпускаете сами: кабинет → раздел «Интеграция» → «Выпустить ключ». Он показывается один раз — сохраните его сразу. Потеряли — выпустите новый, а старый отзовите там же.
Ключ — это доступ к деньгам вашего бизнеса. Держите его в переменных окружения, не в коде и не в репозитории. Ключ интеграции не пускает в панель, а вход владельца не работает с 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. Не указали — заказ оплачивается по ссылке: на телефоне
страница открывает Kaspi с суммой одной кнопкой «Оплатить в Kaspi», без ввода
номера; на компьютере показывает QR.
Дальше отправьте покупателя на 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"}'
В ответ придёт секрет — он показывается один раз, сохраните его сразу. Повторная настройка выпускает новый секрет (так делается ротация).
Ваш обработчик обязан:
- Проверить подпись
X-Kazpayment-Signatureпо сырым байтам тела до разбора JSON. Без этого прислать вам «оплату» сможет кто угодно: адрес приёмника — не секрет. - Ответить 2xx за 10 секунд. Тело ответа мы не читаем. Долгую работу делайте после ответа, а не до.
- Отбрасывать повторы по
event_id. Доставка гарантируется «хотя бы однажды», поэтому одно и то же событие может прийти дважды — закрывайте сделку один раз.
Проверьте приёмник, не дожидаясь настоящей оплаты:
curl -s -X POST https://kazpayment.kz/api/v1/webhook/test \
-H "Authorization: Bearer $KAZPAYMENT_KEY"
Тестовое событие идёт тем же путём и с той же подписью, что настоящие.
Шаг 5. Проверка на живых деньгах
Когда кабинет боевой и касса подключена, проведите одну маленькую оплату
самому себе — например, на 100 ₸, и верните её из кабинета
(Возврат) или запросом
POST /api/v1/orders/<ваш_номер>/refund. Это единственный способ убедиться, что всё
сходится: заказ, оплата, вебхук, учёт.
Чего не делать
Не полагайтесь на вебхук как на единственный источник правды. Если ваш
приёмник лежал полтора суток, событие не дойдёт вовсе. Статус заказа всегда
можно спросить: GET /api/v1/orders/<ваш_номер>.
Не опрашивайте статус чаще раза в минуту — деньги подтверждаются по выписке кассы, и чаще она не обновляется. Действует ограничение частоты запросов; при его превышении вернётся 429.
Не выпускайте QR заранее. Код внутри страницы живёт около трёх минут и создаётся в момент, когда покупатель нажимает кнопку. Печатать и рассылать нужно ссылку, а не картинку кода.
Что делать, если хочется быстрее
Отдайте своему ИИ-ассистенту готовый промпт со страницы
промптов — он прочитает машиночитаемую документацию
(/docs/api.md) и напишет и создание заказа, и приёмник вебхука под ваш стек.
Не помогло? Напишите на support@kazpayment.kz — отвечает разработчик сервиса.