# Платёжные ссылки через POST /payments/link

Создайте платёжную ссылку, QR или deeplink и отправьте покупателю. Kaspi открывается с готовым экраном оплаты.

## Что такое платёжная ссылка?

**Платёжная ссылка** — это URL, который вы отправляете покупателю. Когда он нажимает на ссылку с телефона, открывается приложение Kaspi с уже заполненными данными платежа: суммой и реквизитами продавца. Покупатель видит все детали и нажимает «Оплатить» — всё.

C помощью `POST /v1/payments/link` вы генерируете уникальную **ссылку на оплату**. Её можно вставить как кнопку на web-странице, отправить в SMS, email или мессенджер. Покупателю не нужно знать ваш номер счёта, вводить реквизиты или скачивать приложение отдельно — достаточно нажать на ссылку.

### Ключевое отличие: телефон покупателя не нужен заранее

В отличие от прямых платежей (`POST /v1/payments`), где вы сами указываете номер телефона покупателя, при платёжной ссылке **покупатель сам открывает Kaspi** одним нажатием. Это идеально для:

- **Интернет-магазинов** — кнопка «Оплатить через Kaspi» на странице оформления заказа
- **SMS и мессенджеров** — отправьте ссылку в WhatsApp, Telegram или через SMS сразу после оформления заказа
- **Платёжных страниц** — минималистичная landing page с кнопкой оплаты
- **Анонимных покупок** — ситуации, где покупатель не регистрировался и не давал номер телефона

> **Важно:** ссылка действует около **5 минут** с момента создания. Генерируйте её в момент, когда покупатель готов платить — не вставляйте в email-шаблоны заранее.

---

## Когда использовать платёжные ссылки

### Используйте платёжные ссылки, когда:

- Вы хотите встроить кнопку «Оплатить» прямо на сайт
- Покупатель **не оставлял вам свой номер телефона**
- Нужен **минимальный путь к оплате**: одна ссылка — и он уже в Kaspi
- Вы ведёте **массовую рассылку** с персональными ссылками для каждого клиента
- Вам нужна **оплата без регистрации** пользователя на вашем сайте

### Используйте прямые платежи, когда:

- Номер телефона покупателя уже есть в вашей системе (из его аккаунта)
- Вы хотите сами инициировать push-уведомление в Kaspi покупателю
- Вы обрабатываете **серверную оплату** или подписки

---

## Как это работает: путь за 30 секунд

1. **Вы создаёте платёжную ссылку** — один API-вызов с указанием только суммы
2. **Вы отображаете ссылку** — как кнопку на сайте или отправляете в SMS/мессенджер
3. **Покупатель нажимает** — ссылка открывает приложение Kaspi на его телефоне
4. **Kaspi показывает детали** — название продавца, сумму, опцию бонусов
5. **Покупатель нажимает «Оплатить»** — транзакция завершается
6. **Вы получаете webhook** — ваш сервер уведомляется о завершении

---

## Что нужно для начала

Перед созданием платёжных ссылок убедитесь, что у вас есть:

1. **Зарегистрированное устройство Kaspi** — см. [инструкцию по подключению устройства](https://xpayment.kz/blog/device-setup) с пошаговыми указаниями
2. **Активный API-ключ** (префикс `xdev_...`), привязанный к этому устройству — генерируется при регистрации
3. **Валидная сессия Kaspi** — устройство должно оставаться аутентифицированным; сессии автоматически обновляются платформой каждые 5 минут

> **Первый раз здесь?** Начните с [подключения устройства](https://xpayment.kz/blog/device-setup), чтобы получить API-ключ, затем возвращайтесь для создания первой платёжной ссылки.

---

## Что происходит за кулисами

На диаграмме ниже показан технический поток транзакции через платёжную ссылку. Обратите внимание, что номер телефона покупателя **не требуется при создании** — он появляется только после того, как покупатель нажал на ссылку и оплатил.

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

Когда покупатель нажимает на платёжную ссылку с мобильного телефона, **приложение Kaspi открывается автоматически** — уже с заполненными деталями платежа. Никакого ручного ввода, никаких переходов через браузер.

Важно не путать сам механизм и его визуальную форму:

- на **смартфоне** payment link чаще выглядит как **deeplink или кнопка «Оплатить через Kaspi»**;
- на **desktop checkout** тот же payment link обычно показывают как **QR-код**, который покупатель сканирует телефоном;
- это один и тот же поток `POST /v1/payments/link`, просто с разным входом для покупателя.

### Путь покупателя: от нажатия до оплаты

#### 1. Покупатель получает ссылку
Ссылка может прийти любым удобным способом:
- **Кнопка на сайте** — «Оплатить через Kaspi» прямо на странице оформления заказа
- **Email** — ссылка в письме с выставленным счётом
- **SMS или мессенджер** — WhatsApp, Telegram, обычное SMS

#### 2. Покупатель нажимает на ссылку
Одно нажатие с телефона — и Kaspi открывается автоматически. Браузер переадресует на приложение (deep link). Если Kaspi не установлен — откроется предложение скачать его.

Если же checkout открыт на ноутбуке или большом экране, покупателю удобнее не нажимать deeplink, а **отсканировать QR**. Поэтому на этой странице мы показываем оба примера: mobile deeplink и desktop QR.

#### 3. Покупатель подтверждает платёж
Нажатие на кнопку **«ОПЛАТИТЬ»** запускает транзакцию:
- Kaspi списывает сумму с выбранного способа оплаты
- Покупатель видит анимацию успешного платежа ✓
- Появляется электронный чек

#### 4. Платёж завершён — ваш сервер узнаёт об этом
В течение нескольких секунд:
- Фоновый поллер xpayment обнаруживает статус `COMPLETED`
- Webhook отправляется на ваш сервер с событием `payment.completed`
- Запись платежа содержит номер телефона покупателя (предоставлен Kaspi)

---

### Что если у покупателя нет наllloжения Kaspi?

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

> **Важно:** Ссылка активна примерно 5 минут с момента создания. Если покупатель не успел оплатить — создайте новую ссылку.

---

## API: создание платёжной ссылки

### Запрос

```http
POST /v1/payments/link
Authorization: Bearer xdev_live_abc123...
Content-Type: application/json

{
  "amount": 12000.00
}
```

**Тело запроса:**

| Поле | Тип | Обязательно | Описание |
|------|-----|-------------|----------|
| `amount` | `number` | Да | Сумма платежа в тенге. Должна быть положительной. |

**Заголовки:**

| Заголовок | Значение |
|-----------|----------|
| `Authorization` | `Bearer xdev_...` (ваш API-ключ устройства) |
| `Content-Type` | `application/json` |

---

### Ответ

```json
{
  "payment_link": "https://qr.kaspi.kz/55308082630746899169618031642188672381021",
  "ext_tran_id": "QR14893934009",
  "status": "QrTokenCreated",
  "expire_date": "2026-04-10T12:05:00+05:00"
}
```

**Поля ответа:**

| Поле | Тип | Описание |
|------|-----|----------|
| `payment_link` | `string` | URL для оплаты. Покупатель нажимает на эту ссылку — и Kaspi открывается автоматически. |
| `ext_tran_id` | `string` | Внешний ID транзакции. Используйте его для запроса статуса платежа. |
| `status` | `string` | Всегда `QrTokenCreated` при успехе — означает, что ссылка создана и активна. |
| `expire_date` | `string` | Временна́я метка ISO 8601, когда ссылка истекает (~5 минут с момента создания). |

---

## Как отобразить ссылку покупателю

Получив `payment_link`, вы можете показать его несколькими способами.

> **Помните:** ссылка активна около **5 минут**. Всегда генерируйте её в реальном времени — не сохраняйте заранее и не вставляйте в email-письма.

### Вариант 1: кнопка на сайте (рекомендуется)

```html
<a href="https://qr.kaspi.kz/55308082..." class="kaspi-btn">
  Оплатить через Kaspi — 12 000 ₸
</a>
```

```css
.kaspi-btn {
  display: inline-block;
  background: #00d68f;
  color: #fff;
  padding: 14px 28px;
  border-radius: 10px;
  font-weight: 700;
  text-decoration: none;
}
```

### Вариант 2: ссылка в WhatsApp или Telegram

```
Ваш заказ #1234 на 12 000 ₸ готов к оплате. Оплатите в течение 5 минут:
https://qr.kaspi.kz/55308082...
```

### Вариант 3: TypeScript — генерация и отображение

```typescript
const response = await fetch('/v1/payments/link', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer xdev_live_abc123...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ amount: 12000 }),
})

const { payment_link, ext_tran_id, expire_date } = await response.json()

// Отобразить кнопку
document.getElementById('pay-btn').href = payment_link
document.getElementById('pay-btn').style.display = 'block'

// Или отправить в SMS через вашу SMS-систему
await sendSms(customerPhone, `Оплатите здесь: ${payment_link}`)
```

---

## Истечение срока и повторное создание

Ссылка активна **около 5 минут** со времени создания (`expire_date`). Если покупатель не успел оплатить:

```typescript
const isExpired = new Date() > new Date(expire_date)

if (isExpired) {
  // Создать новую ссылку
  const { payment_link: newLink } = await createPaymentLink(amount)
  updatePayButton(newLink)
}
```

---

## Отслеживание статуса

После создания ссылки используйте `ext_tran_id` для проверки статуса:

```http
GET /v1/payments/{ext_tran_id}
Authorization: Bearer xdev_live_abc123...
```

Или настройте webhook для автоматического уведомления:

| Событие | Когда |
|---------|-------|
| `payment.completed` | Покупатель нажал «Оплатить» и платёж прошёл |
| `payment.canceled` | Покупатель нажал «Отменить покупку» |
| `payment.failed` | Ошибка платежа (недостаточно средств и т.п.) |

→ Подробнее о вебхуках, формате payload и повторных попытках: [Вебхуки: как xpayment уведомляет ваш сервер о платежах](https://xpayment.kz/blog/webhooks).

---

> **Совет:** Для каждого заказа создавайте новую ссылку. Не переиспользуйте одну ссылку для разных покупателей — каждая ссылка привязана к конкретной транзакции в Kaspi.

---

## Читайте также
- [Подключение устройства](https://xpayment.kz/blog/device-setup)
- [Удалённые платежи](https://xpayment.kz/blog/direct-payment)
- [Webhooks xpayment](https://xpayment.kz/blog/webhooks)

---

Источник: https://xpayment.kz/blog/payment-link