Печатный QR для оплаты по счёту или сделке

Кому это нужно

• Ремонт и услуги — лист вкладывается в акт выполненных работ.
• Доставка — лист кладётся в коробку с заказом.
• Договор или квитанция — QR печатается прямо на документе.
• Витрина, прилавок, столик — лист стоит рядом с товаром.

Общее у всех сценариев одно: платить будут не сейчас и не при вас. Именно поэтому обычный QR-счёт здесь не подходит — он живёт минуты.

Что видит покупатель

  [ бумажный лист ]        [ телефон ]            [ Kaspi ]
   Наведите камеру          Магазин «Пример»       Оплата
   ███ ███ ███       →      45 000 ₸        →      45 000 ₸
   ███ ▄▄▄ ███              Ремонт машины          [Оплатить]
   45 000 ₸                 [Открыть Kaspi]

1. Наводит обычную камеру на QR — ту, которой фотографируют.
2. Открывается страница с названием вашего магазина и суммой.
3. Нажимает «Открыть Kaspi» и платит в приложении как обычно.
4. Вам приходит вебхук счёта, покупателю — подтверждение. Повторный скан листа покажет «Оплачено».

Почему «наведите камеру», а не «отсканируйте в Kaspi»

Это главная ошибка в инструкции продавца, и стоит она сорванной оплаты.

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

Правильная формулировка ровно одна: «Наведите камеру телефона на этот код». Она напечатана на самом листе — не пересказывайте её своими словами.

Как сделать

Коды создаются через API — POST /api/v1/static-qr. Тело запроса такое же, как у счёта:

curl -X POST https://api.apipay.kz/api/v1/static-qr \
  -H "X-API-Key: ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 45000,
    "description": "Ремонт стиральной машины",
    "external_order_id": "deal_1024"
  }'

В ответе — адрес для печати, картинка QR и короткий код:

{
  "id": 77,
  "short_code": "K7MP2XQ4",
  "qr_image_url": "https://…/storage/static-qr/….png",
  "amount": "45000.00",
  "status": "active",
  "paid": false,
  "scan_count": 0
}

Организациям с каталогом вместо amount передаётся cart_items — как при создании счёта. description — до 100 символов, это ограничение Kaspi на имя позиции.

⚠️ Поле token в ответе — секрет листа. Кто знает токен, тот может создать счёт от вашего имени. Не показывайте его покупателю, не кладите в ссылки и не сохраняйте в логах. Людям предназначен short_code.

Если разработчика нет — напишите в поддержку из кабинета, раздел «QR для печати»: расскажете, где и как вам удобно размещать код, и мы настроим печать под ваш случай.

Как разместить код на своём бланке

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

1. Не меньше 3 см по стороне. Мелкий код не считывается с расстояния вытянутой руки, а сканируют именно так.
2. Оставьте поля вокруг. Белая рамка шириной примерно в четыре квадратика самого кода.
3. Только чёрный на белом. Без цветного фона, фотографий и градиентов под кодом; цвета не инвертировать.
4. Подпишите код. Рядом обязательно «Наведите камеру телефона» — без этой строки покупатель полезет в приложение Kaspi.
5. Напечатайте короткий код рядом. Если камера не возьмёт — мятая бумага, блик, старый телефон — покупатель введёт код руками.
6. Не растягивайте и не перекрывайте. Код должен остаться квадратным; печать или подпись поверх делают его нечитаемым.

Один лист — одна сделка

По умолчанию лист одноразовый: после оплаты он закрывается, и повторный скан показывает покупателю «Оплачено». На новую сделку печатается новый лист.

Если сделка отменилась или сумма изменилась — отключите лист (DELETE /api/v1/static-qr/{id}) и напечатайте новый. Уже созданные по листу счета при этом не отменяются.

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