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

# Оплата Kaspi по ссылке: как отправить покупателю ссылку

**TL;DR.** Через ApiPay — [API поверх вашего Kaspi Pay](/kaspi-api) — ссылку на оплату Kaspi, которую можно отправить покупателю в WhatsApp или Telegram, получают из одного поля **`payment_url`** в ответе `POST /invoices/qr` с `"static": true` или `POST /static-qr`; номер покупателя не нужен, а счёт появляется, только когда покупатель нажмёт «Оплатить в Kaspi», — поэтому ссылку можно отправить «на потом». Оплату принимает только ссылка, выпущенная в рабочем режиме: выпущенная в песочнице остаётся тестовой навсегда. Если номер покупателя известен и он оплатит в течение суток, надёжнее [счёт по номеру](/guides/kak-sozdat-schet-kaspi-po-nomeru) — он сам придёт покупателю в Kaspi. Если покупатель платит прямо сейчас, хватит обычного QR-счёта: его `qr_token_url` — ссылка Kaspi на уже выпущенный QR, она открывает оплату на телефоне без скана, но живёт минуты, до `qr_expires_at`. Без программиста то же делается в кабинете ApiPay: «Счета → Создать счёт → Ссылка или QR-код» — для оплаты сейчас, раздел «Статический QR» и кнопка «Скопировать ссылку для покупателя» — для оплаты позже. В самом приложении Kaspi Pay покупателю без встречи выставляют [удалённый счёт по номеру телефона](/guides/udalyonnyy-schet-kaspi-pay) — как он устроен, описано в [справке Kaspi](https://guide.kaspi.kz/partner/ru/kaspi_pay/payment/remote_payment/q1484).

## Коротко

| Вопрос | Ответ |
|---|---|
| Что такое ссылка на оплату в ApiPay | Поле `payment_url`: `POST /invoices/qr` со `"static": true` или `POST /static-qr` |
| Можно ли отправить её в WhatsApp или Telegram | Да, это её назначение. Можно и поставить кнопкой на сайте |
| Нужен ли номер телефона покупателя | Нет. Но если номер известен и покупатель оплатит в течение суток, надёжнее счёт по номеру: он сам придёт покупателю в Kaspi |
| Когда создаётся счёт | Когда покупатель нажал «Оплатить в Kaspi»; открытие страницы и предпросмотр в мессенджере счёт не создают |
| Сколько живёт `payment_url` | Пока сделка не оплачена, не отключена и не наступил заданный вами `expires_at` |
| А `qr_token_url`? | Ссылка Kaspi на уже выпущенный QR-счёт: только для оплаты прямо сейчас, живёт минуты — до `qr_expires_at` |
| Ссылку выпустили в песочнице | Она остаётся тестовой навсегда, оплата по ней не пройдёт. После перехода в рабочий режим выпустите новую |
| Как понять, что заплатили | Вебхук со статусом `paid`; у ссылки — ещё `GET /static-qr/{static_qr_id}`, у QR-счёта — `GET /invoices/{id}` |
| Лимит на создание QR-счетов | До 200 QR в минуту на организацию, превышение — `429 qr_rate_limit` |

## Какими способами получить оплату Kaspi через ApiPay?

| | Счёт по номеру | QR-счёт | Ссылка на оплату | Печатный QR |
|---|---|---|---|---|
| Запрос | `POST /invoices` | `POST /invoices/qr` | `POST /invoices/qr` со `"static": true` | `POST /static-qr` |
| Что уходит покупателю | Ничего не отправляете: приходит push в Kaspi | QR на экране (`qr_image_url`) или `qr_token_url` на его телефон | `payment_url` в мессенджер или кнопкой на сайте | Напечатанный лист (`print_url` в его QR) или `payment_url` |
| Когда создаётся счёт | Сразу | Сразу | Когда покупатель нажал «Оплатить в Kaspi» | Когда покупатель нажал «Оплатить в Kaspi» |
| Нужен номер покупателя | Да, `8XXXXXXXXXX` | Нет | Нет | Нет |
| Сколько ждёт оплату | 24 часа | Минуты, до `qr_expires_at` | Пока не оплачена, не отключена и не наступил `expires_at` | Пока лист не оплачен, не отключён и не наступил `expires_at` |
| Когда выбирать | Телефон покупателя известен, push подходит | Покупатель у кассы или платит **в эту минуту** | Покупатель заплатит **позже**: подумает, получит ссылку в чате | Нужен бумажный лист: акт, коробка, договор, витрина |

Правило простое: **ссылка «на потом» — `payment_url`; оплата прямо сейчас — QR-счёт; без ссылки вовсе — счёт по номеру телефона.** Разбор выбора между QR-счётом и печатным QR — «[Какой QR выбрать](/guides/kakoy-qr-vybrat-qr-schet-ili-staticheskiy)».

## Как получить ссылку на оплату через API?

```bash
curl -X POST https://api.apipay.kz/api/v1/invoices/qr \
  -H "X-API-Key: ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "static": true,
    "amount": 5000,
    "description": "Заказ №123",
    "external_order_id": "order-123"
  }'
```

В ответе `201` QR-счёт не создаётся: приходят ссылка **`payment_url`** и её `static_qr_id` — это ID ссылки для `GET /static-qr/{id}`, а не ID счёта, в `/invoices/{id}` его не передают. Покупатель открывает `payment_url` и видит страницу сделки: магазин, сумму и кнопку «Оплатить в Kaspi». По этой кнопке выпускается настоящий Kaspi-QR, затем покупатель нажимает «Открыть Kaspi» и платит в приложении. Счёт появляется только по кнопке, повторное открытие страницы нового счёта не выпускает.

Что важно знать:

- **Выпускайте ссылку в рабочем режиме.** Ссылка, созданная в песочнице, остаётся тестовой навсегда, даже после перехода организации в рабочий режим: покупатель увидит «Тестовый лист. Это песочница: оплата не пройдёт». После перехода выпустите ссылки заново — «[Перешёл в рабочий режим — не работает](/guides/posle-prod-ne-rabotaet)».
- **Описание — до 60 символов**, потому что со страницы можно оплатить и по номеру телефона. Лимит действует для любой ссылки, хотя у ссылки с корзиной и скидкой запасного пути по номеру нет — её оплачивают только по QR.
- **Поле `simulate` в этом режиме не принимается.**
- **Ссылка одноразовая**: одна ссылка — одна сделка.
- **Срок.** `expires_at` необязателен; без него ссылка работает до оплаты или отключения `DELETE /static-qr/{id}`.
- **Код `403 static_qr_disabled`.** Так `static: true` отвечает, если режим ссылок на сервисе выключен. Тогда выпустите лист через `POST /static-qr` и отправьте покупателю его `print_url`.

Ту же ссылку к печатному листу отдаёт `POST /static-qr` — поле `payment_url` рядом с `print_url` (подробнее ниже). Поля запроса и ответа — в [API-документации QR-счёта](/docs#invoices-qr).

## Как отправить ссылку покупателю, который платит прямо сейчас?

Выставьте обычный QR-счёт — без `static`:

```bash
curl -X POST https://api.apipay.kz/api/v1/invoices/qr \
  -H "X-API-Key: ВАШ_КЛЮЧ" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "description": "Заказ №123",
    "external_order_id": "order-123"
  }'
```

Ответ приходит сразу — `201` со статусом `pending`:

```json
{
  "id": 1,
  "amount": "5000.00",
  "status": "pending",
  "is_qr_token": true,
  "qr_token_url": "https://qr.kaspi.kz/...",
  "qr_image_url": "https://.../storage/qr/abc.png",
  "qr_expires_at": "2026-09-03T07:03:00+00:00"
}
```

- **`qr_token_url` — ссылка Kaspi на этот QR-счёт.** На телефоне, где установлено приложение Kaspi, она открывает оплату без сканирования: её можно отправить покупателю, который на связи и платит в эту минуту. Открытая на компьютере ссылка к оплате не приведёт: покажите рядом `qr_image_url`, чтобы человек навёл на экран телефон.
- `qr_image_url` — готовая картинка QR той же оплаты: показывайте её на экране, если покупатель рядом. Рисовать QR самим не нужно.
- `qr_expires_at` — момент, до которого QR успевают открыть, — минуты. Считайте остаток как `qr_expires_at − now` и не зашивайте длительность окна константой: её задаёт Kaspi. Отправлять `qr_token_url` «на потом» нельзя — для этого есть `payment_url`.

То же самое из кода:

```js
const res = await fetch('https://api.apipay.kz/api/v1/invoices/qr', {
  method: 'POST',
  headers: {
    'X-API-Key': process.env.APIPAY_KEY,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 5000,
    description: 'Заказ №123',
    external_order_id: 'order-123',
    external_order_id_idempotency: 'order-123',
  }),
})

const invoice = await res.json()

// Покупатель на связи и платит сейчас — отправляем ссылку Kaspi на QR-счёт
await sendMessage(chatId, `Оплата 5000 ₸: ${invoice.qr_token_url}`)
// invoice.qr_expires_at — до этого момента QR успеют открыть
```

Ключ `X-API-Key` живёт только на сервере. Ссылку покупателю отправляет ваш код, а не браузер покупателя.

## Когда какую ссылку отправлять?

- **Магазин в Instagram или WhatsApp.** Покупатель написал и готов платить в эту минуту — `qr_token_url` в переписку. Говорит «оплачу вечером» или может отвлечься — `payment_url`: пока он думает, счёт не создаётся.
- **Доставка.** Курьер у двери — QR на экране телефона курьера или `qr_token_url` в чат. Заказ оставляют у двери и оплата позже — лист статического QR в коробке или `payment_url` в сообщении.
- **Номер покупателя известен и он оплатит в течение суток.** Надёжнее [счёт по номеру телефона](/guides/kak-sozdat-schet-kaspi-po-nomeru): ссылку не нужно пересылать и открывать, счёт сам придёт покупателю в приложение Kaspi и ждёт 24 часа.
- **Переписка по сделке.** Сумма согласована, а когда покупатель заплатит — неизвестно: `payment_url` одним сообщением. Сумму удобно продублировать текстом — покупатель увидит её и на странице оплаты.
- **Услуги и работы по акту.** Оплату ждут после приёмки — статический QR под сделку. Он лежит в документах и работает через неделю так же, как в день выпуска.
- **Сайт или бот без своего сервера.** API-ключ — серверный секрет, в код, исполняемый в браузере, его класть нельзя. Пока сервера нет, выставляйте счёт в кабинете и отправляйте ссылку руками; когда сервер появится, тот же сценарий переносится в API без изменений для покупателя. Разбор по площадкам — «[ApiPay для интернет-магазина](/guides/apipay-dlya-internet-magazina)» и «[Kaspi-оплата в Telegram-боте](/guides/kaspi-oplata-v-telegram-bote)».

## Ссылка перестала открываться — что делать?

Если это `qr_token_url`, чинить ничего не нужно: истёкший QR означает ровно одно — покупатель не успел, нужен новый QR-счёт. Продления нет, повторный запрос на тот же заказ создаст новый QR. Приложение Kaspi в этот момент показывает покупателю «Попробуйте позже» — разбор этого экрана в статье «[QR показывает «Попробуйте позже»](/guides/qr-poprobuyte-pozzhe)».

Если QR регулярно не успевают открыть — сценарий не «сейчас», а «потом»: перенесите его на `payment_url`, статический QR или счёт по номеру телефона. Пересоздавать QR-счёт по кругу не стоит: каждый созданный QR-счёт, в том числе сгоревший, занимает место в [дневном лимите тарифа](/guides/limit-schetov-po-tarifu).

QR-счета **сосуществуют**: новый не отменяет прежние, каждый созданный оплачиваем до своего истечения. Двум покупателям в очереди можно спокойно выдать по своему QR.

`payment_url` сама не сгорает: она перестаёт работать, когда сделка оплачена, ссылку отключили или наступил заданный вами `expires_at`.

## Как понять, что покупатель заплатил?

Ждите вебхук со статусом `paid`. Без вебхуков статус читают запросом: у QR-счёта — `GET /invoices/{id}`, у ссылки на оплату и печатного листа — `GET /static-qr/{static_qr_id}` (поле `paid`). Вебхуки счетов, созданных по ссылке, несут `static_qr_code_id` и ваш `external_order_id`. Настройка — «[Как настроить вебхуки ApiPay](/guides/nastroyka-webhookov-apipay)».

⚠️ **Событие `invoice.qr_scanned` — не оплата.** Оно приходит, когда покупатель открыл оплату: статус счёта остаётся `pending`, добавляется маркер `qr_substate: "scanned"`. Как и любое событие, оно может продублироваться при повторной доставке — дедуплицируйте по паре `(invoice.id, invoice.status)`. После него возможны и `paid`, и `cancelled` — покупатель мог закрыть приложение, не подтвердив. Интерфейс кассы должен уметь вернуться из «Ожидается подтверждение» обратно в исходное состояние.

Отменить QR-счёт нельзя: `POST /invoices/{id}/cancel` отвечает `409 qr_cancel_unsupported`, статус не меняется. Делать при этом ничего не нужно — QR гаснет сам и счёт уезжает в `expired`. Отмена работает у счетов по номеру телефона, ссылка на оплату и лист отключаются `DELETE /static-qr/{id}`. Если покупатель успел оплатить счёт с неверной суммой, деньги возвращаются обычным возвратом `POST /invoices/{id}/refund`, а не отменой.

⚠️ **В песочнице отмена ведёт себя иначе:** тестовый QR-счёт отменяется как обычный — `200` и статус `cancelled`. Не калибруйте по этому боевую логику: в рабочем режиме придёт `409 qr_cancel_unsupported`. Подробнее — «[Сколько живёт QR-счёт](/guides/qr-schet-ttl-i-limity)».

## Что нужно знать до первого запроса?

- **Описание.** У QR-счёта — до 100 символов, это наименование позиции в чеке Kaspi. У ссылки `static: true` — до 60 символов.
- **Частота — до 200 QR в минуту на организацию.** Превышение даёт `429 qr_rate_limit`; лимит общий на организацию, не на ключ и не на кассира, и действует в том числе в песочнице. Отдельно работает суточный лимит тарифа — «[Дневной лимит счетов по тарифу](/guides/limit-schetov-po-tarifu)».
- **Организация с каталогом.** QR-счёт, ссылку на оплату и статический QR такой организации выдаёт только запрос с корзиной: `POST /invoices/qr` и `POST /static-qr` с одним `amount` вернут `422` с `error_code: catalog_requires_cart_items`. Передавайте `cart_items` — «[Счета с корзиной](/guides/scheta-s-korzinoy-cart-items-ofd)».
- **Песочница.** В тестовом режиме реальных оплат нет; у QR-счёта поле `simulate` (`paid`, `cancelled`, `expired`) позволяет проверить все исходы — «[Песочница и рабочий режим](/guides/pesochnitsa-i-rabochiy-rezhim)». Ссылки и листы, выпущенные в песочнице, тестовыми и остаются: для покупателей выпускайте их после перехода в рабочий режим.

## Чем печатный QR отличается от ссылки на оплату?

Печатный (статический) QR выпускается под одну сделку и ждёт покупателя на бумаге:

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

В ответе — `print_url` (адрес листа, его кодирует QR на листе), восьмисимвольный `short_code` для ручного ввода, `manual_url` (куда этот код вводят), `qr_image_url` — непротухающая картинка QR для печати — и `payment_url`, ссылка на оплату той же сделки, которую можно отправить вместо печати. Если режим ссылок на сервисе выключен, `payment_url` приходит `null` — тогда отправьте покупателю `print_url`: лист от этого режима не зависит. Лист, выпущенный в песочнице, как и ссылка, остаётся тестовым навсегда. В кабинете кнопка «Скопировать ссылку для покупателя» у листа копирует его `print_url`.

Покупатель откроет страницу с названием магазина и суммой, нажмёт «Оплатить в Kaspi» — в этот момент создаётся счёт, — затем «Открыть Kaspi» и заплатит. Если приложение не открылось, на странице есть запасной путь — покупатель вводит свой номер телефона и получает запрос на оплату push-уведомлением. Что видит покупатель на самом счёте в Kaspi — «[Что видит покупатель](/guides/chto-vidit-pokupatel)».

Лист привязан к одной сделке: после оплаты повторное открытие показывает «Оплачено». Сумма изменилась или сделка отменилась — отключите лист (`DELETE /api/v1/static-qr/{id}`) и выпустите новый; описание у выпущенного листа не меняется. Ссылка листа и её токен — это и есть доступ к оплате: не выкладывайте лист туда, где он не нужен. Подробности печати и вёрстки — «[Статический QR для оплаты по счёту или сделке](/guides/pechatnyy-qr-dlya-oplaty-po-sdelke)».

У ссылки на оплату и листа место в лимите тарифа занимает не сама ссылка, а счета: каждый Kaspi-QR, выпущенный после нажатия «Оплатить в Kaspi». Если QR истёк, а его не сканировали, открытая страница сама выпускает новый счёт, без нажатия, — он тоже считается. Подробнее — «[Лимит счетов по тарифу](/guides/limit-schetov-po-tarifu)».

## А поле kaspi_qr_link — это тоже ссылка?

У обычного счёта по номеру телефона в карточке есть поле `kaspi_qr_link` — QR-ссылка Kaspi на **этот** счёт. Она вычисляется из идентификатора, который Kaspi присваивает счёту, поэтому появляется не сразу: пока счёт в `processing`, поле `null`, и в песочнице оно `null` всегда.

Строить на нём сценарий «отправить покупателю ссылку» не стоит: для этого есть `payment_url`, а для оплаты прямо сейчас — `qr_token_url` QR-счёта. Про сам счёт по номеру — «[Как создать счёт по номеру](/guides/kak-sozdat-schet-kaspi-po-nomeru)».

## Как получить ссылку в кабинете без программиста?

Разработчик для ссылки не обязателен.

- **Покупатель платит сейчас.** **Счета → Создать счёт → переключатель «Ссылка или QR-код».** Номер покупателя вводить не нужно — достаточно суммы и описания. После создания под QR-кодом видна ссылка и две кнопки: **«Открыть в Kaspi»** — проверить, как это выглядит у покупателя, и **«Скопировать ссылку»** — вставить её в WhatsApp или Telegram. QR и ссылка действуют несколько минут.
- **Покупатель заплатит позже.** Раздел **«Статический QR»**: создайте лист под сделку и в меню листа нажмите **«Скопировать ссылку для покупателя»** — скопируется адрес листа (`print_url`). Он работает, пока лист не оплачен и не отключён.

## Вопросы и ответы

**Как дать ссылку на оплату Kaspi?**
Через ApiPay: запрос `POST /invoices/qr` с `"static": true` возвращает `payment_url` — ссылку на оплату, которую отправляют покупателю в мессенджер. Номер покупателя не нужен, счёт появится, когда он нажмёт «Оплатить в Kaspi». Ссылку для покупателей выпускайте в рабочем режиме: выпущенная в песочнице остаётся тестовой. В кабинете ApiPay — раздел «Статический QR», кнопка «Скопировать ссылку для покупателя».

**Можно ли отправить ссылку на оплату Kaspi в WhatsApp?**
Да. Отправьте `payment_url`: ссылка работает, пока сделка не оплачена или не отключена, поэтому покупатель может заплатить позже. Если он на связи и платит в эту минуту, подойдёт и `qr_token_url` QR-счёта — в кабинете это кнопка «Скопировать ссылку», но QR действует минуты.

**Сколько живёт ссылка на оплату?**
`payment_url` работает, пока сделка не оплачена, не отключена и не наступил заданный вами `expires_at`. `qr_token_url` QR-счёта действует минуты — до `qr_expires_at` из ответа; длительность окна задаёт Kaspi, продлить нельзя, нужен новый QR-счёт.

**Чем ссылка на оплату отличается от QR-счёта?**
Моментом создания счёта и сроком. У QR-счёта счёт выпускается сразу и живёт минуты — он для оплаты прямо сейчас. У `payment_url` счёт появляется, только когда покупатель нажал «Оплатить в Kaspi», поэтому ссылку можно отправить «на потом», и пока покупатель думает, лимит тарифа не тратится.

**Ссылку создали в песочнице — заработает ли она после перехода в рабочий режим?**
Нет. Ссылка и печатный лист, выпущенные в песочнице, остаются тестовыми навсегда: покупатель увидит «Тестовый лист», оплата не пройдёт. После перехода в рабочий режим выпустите новые ссылки и листы, а старые отключите.

**Нужен ли номер телефона покупателя?**
Нет. Ни ссылке на оплату, ни QR-счёту номер не нужен. Номер требуется только счёту по номеру телефона (`POST /invoices`), где покупателю приходит push. Если номер известен и покупатель оплатит в течение суток, такой счёт надёжнее ссылки: его не нужно пересылать и открывать.

**Как понять, что по ссылке заплатили?**
По вебхуку со статусом `paid`, либо запросом: `GET /static-qr/{static_qr_id}` для ссылки на оплату, `GET /invoices/{id}` для QR-счёта. Событие `invoice.qr_scanned` означает только, что покупатель открыл оплату: статус остаётся `pending`, и после скана возможна отмена. Дожидайтесь `paid`.

**Можно ли отменить ссылку, если покупатель передумал?**
Ссылка на оплату и печатный лист отключаются запросом `DELETE /api/v1/static-qr/{id}`. У QR-счёта отмены нет — `POST /invoices/{id}/cancel` вернёт `409 qr_cancel_unsupported`; делать ничего не нужно, QR погаснет сам.

Смотрите также: [Какой QR выбрать](/guides/kakoy-qr-vybrat-qr-schet-ili-staticheskiy) · [QR-счёт: сколько живёт и какие лимиты](/guides/qr-schet-ttl-i-limity) · [Статический QR](/guides/pechatnyy-qr-dlya-oplaty-po-sdelke) · [Удалённый счёт в Kaspi Pay](/guides/udalyonnyy-schet-kaspi-pay) · [Счёт по номеру телефона через API](/invoice-by-phone) · пиллар «[Как принимать оплату Kaspi через API](/kaspi-api)».

---

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