> Источник: https://apipay.kz/guides/pechatnyy-qr-dlya-oplaty-po-sdelke · Обновлено: 2026-10-24 · apipay.kz
> ApiPay — независимый сервис приёма платежей поверх вашего Kaspi Pay.

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

**TL;DR.** Статический QR, который выпускает ApiPay, — код под конкретную сделку. Вы печатаете лист с ним и отдаёте его вместе с актом, кладёте в коробку или ставите на витрину. Покупатель **наводит камеру телефона** — открывается страница с суммой. Он нажимает «Оплатить в Kaspi», и только в этот момент создаётся счёт; дальше — «Открыть Kaspi» и оплата в приложении. Деньги и вебхук приходят вам как по обычному счёту. Лист работает, пока его не оплатят или не отключат, и привязан к одной сделке: после оплаты закрывается. Печать — не единственный способ доставки: `print_url` из ответа — адрес страницы оплаты листа, его можно отправить покупателю в мессенджер, и в отличие от `qr_token_url` QR-счёта он не истекает через минуты. Статический QR — для случаев, когда клиент заплатит позже; если он платит сразу, рядом с вами, нужен QR-счёт — «[Какой QR выбрать](/guides/kakoy-qr-vybrat-qr-schet-ili-staticheskiy)».

## Коротко

| Вопрос | Ответ |
|---|---|
| Чем отличается от QR-счёта | QR-счёт и его `qr_token_url` живут минуты; статический QR и его `print_url` — пока лист не оплачен и не отключён |
| Когда создаётся счёт | Когда покупатель нажал «Оплатить в Kaspi»; открытие страницы счёт не создаёт |
| Лимит тарифа | Созданный в кабинете — не входит; созданный через API — место занимает каждый выпущенный по нему Kaspi-QR, в том числе автоматический перевыпуск |
| Можно ли отправить ссылку | Да: `print_url` открывает ту же страницу оплаты, что и скан кода. В ответе есть и ссылка на оплату `payment_url` той же сделки |
| Чем сканировать | **Обычной камерой телефона**, не сканером внутри Kaspi |
| Сколько сделок на листе | Одна: после оплаты лист закрывается |
| Нужен ли кассир на месте | Нет, но кассир должен быть подключён к организации |

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

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

Общее у всех сценариев одно: **платить будут не сейчас и не при вас**.

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

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

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

Если приложение Kaspi не открылось, на странице есть запасной путь «Оплатить по номеру телефона»: покупатель вводит свой номер и получает пуш-запрос на оплату. Создаётся обычный счёт по номеру (`is_qr_token: false`) с тем же `external_order_id`; повторная отправка того же номера второго счёта не создаёт. У листа с корзиной и скидкой этого пути нет — такой лист оплачивается только по QR (подробнее — в разделе «Как сделать»).

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

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

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

## Как сделать

Коды создаются через [API ApiPay](/kaspi-api) — `POST /api/v1/static-qr`, поля запроса и ответа — в [API-документации статического QR](/docs#static-qr-create). Тело запроса такое же, как у счёта:

```bash
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"
  }'
```

ИИН/БИН покупателя (`buyer_bin`) листу не задаётся: покупатель при печати неизвестен, и запрос с этим полем вернёт `422`.

В ответе — картинка QR, короткий код и адрес, куда этот код вводят:

```json
{
  "id": 77,
  "token": "9f1c…",
  "short_code": "K7MP2XQ4",
  "print_url": "https://qr.apipay.kz/9f1c…",
  "manual_url": "https://qr.apipay.kz",
  "qr_image_url": "https://…/storage/static-qr/….png",
  "payment_url": "https://…",
  "amount": "45000.00",
  "status": "active",
  "paid": false,
  "scan_count": 0
}
```

`print_url` — ссылка на страницу оплаты этой сделки; она же зашита в QR-код листа. Поэтому лист не обязательно печатать: ту же ссылку можно отправить покупателю в WhatsApp или Telegram, положить в письмо с актом или в карточку заказа. Покупатель откроет её в браузере телефона, увидит название магазина и сумму, нажмёт «Оплатить в Kaspi», затем «Открыть Kaspi» и заплатит; если Kaspi не открылся — на той же странице введёт свой номер и получит push. Ссылка не истекает: она работает, пока лист не оплачен и не отключён (либо до `expires_at`, если вы его задали при создании) — этим она и отличается от `qr_token_url` [QR-счёта](/guides/qr-schet-ttl-i-limity), ссылки Kaspi на уже выпущенный QR, которая живёт минуты. Рядом в ответе приходит `payment_url` — ссылка на оплату той же сделки, её тоже можно отправить вместо печати; если режим ссылок выключен, `payment_url` приходит `null`, и покупателю отправляют `print_url` — «[Оплата Kaspi по ссылке](/guides/oplata-po-ssylke-kaspi)». Запасной путь для тех, у кого лист на бумаге, — `short_code` и `manual_url`.

⚠️ Ссылка — это доступ к оплате сделки (подробнее ниже), поэтому отправляйте её адресно тому покупателю, для которого лист выпущен.

Сумму листа берите целой в тенге: покупатель может выбрать оплату по номеру телефона, а такой счёт принимает только целые тенге — при дробной сумме оплата по номеру не пройдёт. Оплата сканированием QR дробную сумму принимает.

Организация с каталогом статический QR сделать может, но **обязана** передать `cart_items` вместо `amount` — как при создании QR-счёта; запрос одной суммой вернёт `422` с `error_code: catalog_requires_cart_items`. `description` — до 100 символов, это ограничение Kaspi на имя позиции.

**Скидка на листе** — `discount_percentage`, только целый процент от 1 до 99. Она применяется только к позициям `cart_items`: на листе одной суммой (`amount`) скидка ни на что не влияет. Скидку строки считают так же, как на QR-счёте: процент от цены строки с округлением вверх до целого тенге. Правило и примеры — «Как считается скидка на QR-счёте?» в статье «[Счета с корзиной](/guides/scheta-s-korzinoy-cart-items-ofd)». Позицию с ценой в тиынах и позицию, которую скидка обнуляет, лист со скидкой не примет: выпуск отбивается `422 qr_discount_unsupported`.

Цену позиции, для которой не передан `price`, лист берёт из каталога в момент оплаты, а не при выпуске. Если цена такой позиции в каталоге станет дробной, лист со скидкой перестанет принимать оплату. Чтобы цена на листе со скидкой не зависела от каталога, задавайте её полем `price` в строке корзины — в целых тенге.

⚠️ **Лист с корзиной и скидкой оплачивается только по QR.** Запасного пути «Оплатить по номеру телефона» на его странице нет: у счёта по номеру скидка считается по другому правилу, и сумма разошлась бы с напечатанной. Если покупателю нужен и этот путь, выпускайте лист без скидки, а уценённые цены в целых тенге задайте полем `price` в строках корзины. Итог по деньгам тот же, но скидки не будет отдельной строкой в чеке, а в вебхуке не придут `subtotal` и `discount_sum`.

⚠️ **Описание листа задаётся один раз — у уже выпущенного листа изменить его нельзя.** Это важно из-за запасного пути: оплата по номеру телефона уходит обычным счётом, а у такого счёта описание не длиннее **60 символов**. Оплата сканированием QR не затрагивается — там прежний лимит 100. Поэтому слишком длинное описание отбивается прямо при выпуске листа — `422 description_too_long`: лист, у которого оплата по номеру не сработала бы, просто не создастся. У уже напечатанного листа с длинным описанием путь один — отключить его (`DELETE /api/v1/static-qr/{id}`) и напечатать новый.

⚠️ **Если каталог у вас пока выключен, а Kaspi Касса есть** — печатать листы одной суммой сейчас можно, но в момент включения каталога **уже напечатанные листы перестанут работать**, а переиздать их нельзя. Порядок перехода и что сказать нам заранее — в статье [Переход на каталог товаров](/guides/perehod-na-katalog-tovarov).

⚠️ **Ссылка листа (`print_url`) и её `token` — это и есть доступ к оплате: они зашиты в QR-код.** Значит, открыть страницу оплаты этой сделки сможет любой, у кого есть лист или его фотография. Печатайте лист под конкретную сделку и не выкладывайте его туда, где он не нужен; в логи и переписку кладите `id` и `external_order_id`, а не токен. Если лист ушёл не тому — отключите его (`DELETE /api/v1/static-qr/{id}`) и напечатайте новый.

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

## Статический QR и лимит тарифа

Счёт по статическому QR создаётся не при выпуске листа и не при открытии страницы, а только когда покупатель нажал «Оплатить в Kaspi». Пока клиент думает, лимит тарифа не тратится.

- **Создан в кабинете** — в лимит не входит: у такого кода нет API-ключа.
- **Создан через API** — место в лимите занимает каждый Kaspi-QR, выпущенный после нажатия «Оплатить в Kaspi».
- У одноразового листа (так по умолчанию) повторное нажатие, пока выпущенный QR действует и не отсканирован, нового счёта не создаёт.
- У многоразового листа (`single_use: false`) каждое нажатие выпускает новый счёт, и каждый занимает место в лимите.
- QR истёк, а его не сканировали, — открытая страница сама выпускает новый счёт, без нажатия, и он тоже занимает место в лимите. Число таких перевыпусков подряд ограничено.
- Запасная оплата по номеру телефона тоже создаёт счёт, и он тоже считается.

Поэтому один лист не всегда равен одному счёту. Как считается лимит — «[Лимит счетов по тарифу](/guides/limit-schetov-po-tarifu)».

⚠️ **Пока код у покупателя, оплата по нему зависит от состояния вашей организации.** Если дневной лимит тарифа исчерпан, тариф не оплачен или кассир отключён, покупатель, нажавший «Оплатить в Kaspi», увидит «Оплата недоступна» — причину страница ему не называет, и вам об этом ничего не приходит.

Если у клиентов на руках есть распечатанные коды, следите за расходом лимита на главной кабинета или в `GET /api/v1/tariff` → `daily_usage` (тем же ключом API, что и счета) и держите тариф оплаченным.

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

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

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

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

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

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

⚠️ **Лист, выпущенный в песочнице, остаётся тестовым навсегда** — и после перехода организации в рабочий режим. Покупатель увидит «Тестовый лист. Это песочница: оплата не пройдёт». В API у такого листа `is_sandbox: true` (`GET /api/v1/static-qr/{id}`). Листы для покупателей выпускайте в рабочем режиме, а тестовые замените — «[Перешёл в рабочий режим — не работает](/guides/posle-prod-ne-rabotaet)».

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

**Сколько живёт напечатанный лист?**
Пока его не оплатят или не отключат (`DELETE /api/v1/static-qr/{id}`). Срок годности можно задать заранее полем `expires_at` при создании листа (дата в будущем).

**Что если камера совсем не берёт код?**
Покупатель открывает **qr.apipay.kz** в браузере телефона и вводит напечатанный на листе код из восьми символов — попадает на ту же страницу оплаты. Регистр, дефисы и пробелы в коде значения не имеют.

**Что если кассир отключился?**
Лист напечатается и без подключённого кассира — их печатают заранее. Но при нажатии «Оплатить в Kaspi» счёт не создастся, поэтому кассира нужно [подключить](/connect-cashier) до того, как лист попадёт покупателю. ⚠️ Если у организации **несколько** активных кассиров и нет основного, создание листа отобьётся сразу: `422 connection_ambiguous` — передайте `kaspi_connection_id` явно. Чужой или неактивный `kaspi_connection_id` тоже даёт `422`, а не `404`.

**Как я узнаю, что по листу заплатили?**
Обычным вебхуком счёта (`invoice.status_changed`) — отдельного события у листа нет.

Сопоставляйте счёт с листом по `static_qr_id` (в вебхуке — `invoice.static_qr_id`, прежнее имя `static_qr_code_id`, это `id` листа), а если его не сохранили — по `external_order_id`: в счёт попадает тот, что вы задали при создании листа, а если не задавали — подставляется `static_qr_{id листа}_{unix-время}`; состояние листа читается из `GET /api/v1/static-qr/{id}` (`paid`, `paid_at`, `scan_count`).

⚠️ Счета одного листа могут делить одно `external_order_id`: новый счёт после истечения QR, новый QR по просьбе покупателя поверх уже отсканированного, запасная оплата по номеру телефона. Во втором случае оплатить могут оба QR — обрабатывайте `paid` по каждому `invoice.id`, а лишний платёж верните или передайте на проверку человеку — решите это заранее.

**Можно ли сделать скидку на листе?**
Да, через API: `discount_percentage` (целый процент от 1 до 99) вместе с `cart_items`. Скидка строки округляется вверх до целого тенге, как на QR-счёте. Такой лист оплачивается только по QR — оплаты по номеру телефона на его странице нет.

**Работает ли лист без интернета у покупателя?**
Нет: камера открывает страницу оплаты в браузере, а дальше нужен Kaspi. Интернет покупателю необходим.

---

ApiPay — независимый сервис и не аффилирован с АО «Kaspi Bank». Kaspi и Kaspi Pay — товарные знаки их правообладателя.
База знаний: https://apipay.kz/guides