Создайте платёжную ссылку, QR или deeplink и отправьте покупателю. Kaspi открывается с готовым экраном оплаты.
Платёжная ссылка — это URL, который вы отправляете покупателю. Когда он нажимает на ссылку с телефона, открывается приложение Kaspi с уже заполненными данными платежа: суммой и реквизитами продавца. Покупатель видит все детали и нажимает «Оплатить» — всё.
C помощью POST /v1/payments/link вы генерируете уникальную ссылку на оплату. Её можно вставить как кнопку на web-странице, отправить в SMS, email или мессенджер. Покупателю не нужно знать ваш номер счёта, вводить реквизиты или скачивать приложение отдельно — достаточно нажать на ссылку.
В отличие от прямых платежей (POST /v1/payments), где вы сами указываете номер телефона покупателя, при платёжной ссылке покупатель сам открывает Kaspi одним нажатием. Это идеально для:
Важно: ссылка действует около 5 минут с момента создания. Генерируйте её в момент, когда покупатель готов платить — не вставляйте в email-шаблоны заранее.
Перед созданием платёжных ссылок убедитесь, что у вас есть:
xdev_...), привязанный к этому устройству — генерируется при регистрацииПервый раз здесь? Начните с подключения устройства, чтобы получить API-ключ, затем возвращайтесь для создания первой платёжной ссылки.
На диаграмме ниже показан технический поток транзакции через платёжную ссылку. Обратите внимание, что номер телефона покупателя не требуется при создании — он появляется только после того, как покупатель нажал на ссылку и оплатил.
Когда покупатель нажимает на платёжную ссылку с мобильного телефона, приложение Kaspi открывается автоматически — уже с заполненными деталями платежа. Никакого ручного ввода, никаких переходов через браузер.
Важно не путать сам механизм и его визуальную форму:
POST /v1/payments/link, просто с разным входом для покупателя.Ссылка может прийти любым удобным способом:
Одно нажатие с телефона — и Kaspi открывается автоматически. Браузер переадресует на приложение (deep link). Если Kaspi не установлен — откроется предложение скачать его.
Если же checkout открыт на ноутбуке или большом экране, покупателю удобнее не нажимать deeplink, а отсканировать QR. Поэтому на этой странице мы показываем оба примера: mobile deeplink и desktop QR.
Нажатие на кнопку «ОПЛАТИТЬ» запускает транзакцию:
В течение нескольких секунд:
COMPLETEDpayment.completedПри нажатии на ссылку браузер попытается открыть приложение Kaspi. Если оно не установлено — покупатель попадёт на страницу Kaspi в браузере, где сможет скачать приложение или войти через веб-версию.
Важно: Ссылка активна примерно 5 минут с момента создания. Если покупатель не успел оплатить — создайте новую ссылку.
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 |
{
"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-письма.
<a href="https://qr.kaspi.kz/55308082..." class="kaspi-btn">
Оплатить через Kaspi — 12 000 ₸
</a>
.kaspi-btn {
display: inline-block;
background: #00d68f;
color: #fff;
padding: 14px 28px;
border-radius: 10px;
font-weight: 700;
text-decoration: none;
}
Ваш заказ #1234 на 12 000 ₸ готов к оплате. Оплатите в течение 5 минут:
https://qr.kaspi.kz/55308082...
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). Если покупатель не успел оплатить:
const isExpired = new Date() > new Date(expire_date)
if (isExpired) {
// Создать новую ссылку
const { payment_link: newLink } = await createPaymentLink(amount)
updatePayButton(newLink)
}
После создания ссылки используйте ext_tran_id для проверки статуса:
GET /v1/payments/{ext_tran_id}
Authorization: Bearer xdev_live_abc123...
Или настройте webhook для автоматического уведомления:
| Событие | Когда |
|---|---|
payment.completed |
Покупатель нажал «Оплатить» и платёж прошёл |
payment.canceled |
Покупатель нажал «Отменить покупку» |
payment.failed |
Ошибка платежа (недостаточно средств и т.п.) |
→ Подробнее о вебхуках, формате payload и повторных попытках: Вебхуки: как xpayment уведомляет ваш сервер о платежах.
Совет: Для каждого заказа создавайте новую ссылку. Не переиспользуйте одну ссылку для разных покупателей — каждая ссылка привязана к конкретной транзакции в Kaspi.