Create a payment link through API v2 and send it to the buyer any way you like: Kaspi opens with the payment screen ready. QR, deeplink, lifetime, and re-creation.
A payment link is a Kaspi QR or deeplink for a specific amount. You create it with a POST /v2/payments/link request and give it to the buyer any convenient way: a button on a website, a QR on a screen, a WhatsApp or Telegram message, an email. The buyer opens the link, the Kaspi app launches with the payment already filled in, and all that is left is to tap “Pay”.
Unlike a phone invoice, you do not need to know the buyer’s number. You create the link with only an amount and a register, and the buyer decides when and from which device to open it.
If there is no developer, you can create the same links in the dashboard without code: Accept payments without coding.
Your server -> POST /v2/payments/link -> xpayment -> Kaspi QR
| |
| qr_token (link / QR) |
v v
The buyer opens the link -> Kaspi -> "Pay" -> payment.completed webhook
POST /v2/payments/link with device_name, amount, and (preferably) merchant_order_id.qr_token, payment_id, and expire_date.qr_token as a QR or a button.payment.completed webhook, and you fulfill the order.| What you need | More |
|---|---|
| A connected register with an API name | Connecting a cash register and getting an API v2 key |
An API v2 key xapi_… |
The API-ключи (API keys) section → Ключи API v2 (API v2 keys) |
| A webhook | xpayment webhooks |
PENDING.payment.completed, payment.expired, and so on), xpayment sends a webhook.API v1: the same flow through
POST /v1/payments/linkwith a register keyxdev_…(withoutdevice_name). It is still supported.
When the buyer taps a payment link on a mobile phone, the Kaspi app opens automatically with the payment details already filled in. Nothing has to be typed by hand.
Do not confuse the mechanism with how it looks:
POST /v2/payments/link flow, just with a different way in for the buyer.The link can arrive any way:
One tap on a phone opens Kaspi. If the checkout is open on a laptop, it is easier for the buyer not to tap a deeplink but to scan the QR. That is why both are shown below: the mobile deeplink and the QR on a computer.
Tapping Pay starts the transaction: Kaspi charges the amount, the buyer sees a confirmation and gets an electronic receipt.
Within a few seconds xpayment notices the COMPLETED status and sends your server the payment.completed webhook. The payment record contains the buyer’s phone number, as provided by Kaspi.
When the link is tapped, the browser tries to open the Kaspi app. If it is not installed, the buyer lands on a Kaspi page where they can download the app or sign in through the web version.
Important: the link does not last long. The exact time is in the
expire_datefield of the response, usually a few minutes. If the buyer did not make it in time, create a new link.
curl -X POST https://api.xpayment.kz/v2/payments/link \
-H "Authorization: Bearer xapi_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{
"device_name": "Kassa1",
"amount": 1500,
"merchant_order_id": "order-42"
}'
| Field | Type | Required | Description |
|---|---|---|---|
device_name |
string | yes | The name of your register, for example Kassa1 |
amount |
number | yes | The amount in tenge |
merchant_order_id |
string | no | Your order identifier. It comes back in the webhook |
200{
"payment_id": "018f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
"qr_token": "https://qr.kaspi.kz/553080826307468991696180316421",
"qr_operation_id": 14893934009,
"ext_tran_id": "QR14893934009",
"status": "QrTokenCreated",
"expire_date": "2026-11-08T16:39:53.000+05:00",
"environment": "live"
}
| Field | Meaning |
|---|---|
payment_id |
The payment ID in xpayment: you use it to request the status, cancel the payment, and make a refund |
qr_token |
The Kaspi QR address: show it as a QR or use it as a deeplink |
qr_operation_id, ext_tran_id |
Operation identifiers in Kaspi |
status |
The QR token status at the moment of creation |
expire_date |
When the link stops working |
environment |
live for a live key, sandbox for a test key |
<a href="https://qr.kaspi.kz/…" class="pay-button">Pay with Kaspi</a>
On a phone, tapping it opens Kaspi. Insert the qr_token from the response on the server and serve the page ready.
Draw qr_token as a QR code with any library (for example, qrcode for JavaScript or segno for Python). The buyer scans it with the phone camera or the Kaspi app.
Send qr_token as text: Pay for order #42: https://qr.kaspi.kz/…. The link is clickable and opens Kaspi.
async function startCheckout(orderId: string, amount: number) {
const res = await fetch("https://api.xpayment.kz/v2/payments/link", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.XPAYMENT_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
device_name: process.env.XPAYMENT_DEVICE_NAME,
amount,
merchant_order_id: orderId,
}),
})
if (!res.ok) throw new Error(`xpayment ${res.status}`)
const link = await res.json()
await db.orders.update(orderId, { paymentId: link.payment_id }) // link the order and the payment
return { url: link.qr_token, expiresAt: link.expire_date }
}
import os
import httpx
def create_link(amount: float, order_id: str) -> dict:
resp = httpx.post(
"https://api.xpayment.kz/v2/payments/link",
headers={"Authorization": f"Bearer {os.environ['XPAYMENT_API_KEY']}"},
json={
"device_name": os.environ["XPAYMENT_DEVICE_NAME"],
"amount": amount,
"merchant_order_id": order_id,
},
timeout=15,
)
resp.raise_for_status()
return resp.json()
A link is short-lived: look at expire_date. If the time runs out, the payment gets the status EXPIRED and the payment.expired webhook arrives. For a new attempt, create a new link.
One order can have several links: the buyer walked away, the QR went stale, a cashier created the link again. That is why merchant_order_id identifies an order, not a payment, and several payments can be linked to one value.
When you create a new link with the same merchant_order_id, the earlier unpaid links of that order are cancelled, so only one stays live. No cancellation webhook is sent in that case: otherwise an order could get payment.expired from an abandoned link after payment.completed for the paid one.
The only exception: if Kaspi has already reported that an earlier link was paid, it is kept and completes as usual with payment.completed.
Reconcile webhooks by
payment_id, not bymerchant_order_id.
payment.completed, payment.expired, payment.cancelled, payment.failed. Verify the signature, then fetch the payment by payment_id: Webhooks, Signature verification.GET /v2/payments/{payment_id} every 3–5 seconds.GET /v2/payments?merchant_order_id=order-42&status=COMPLETED.Statuses and refund rules: Payment statuses and refunds.
| HTTP | Code | Cause |
|---|---|---|
| 400 | VALIDATION_ERROR |
device_name or amount is missing |
| 401 | — | The key is missing, revoked, or not an xapi_ key |
| 404 | DEVICE_NOT_FOUND |
There is no active register with this name |
| 422 | KASPI_ERROR, DEVICE_INACTIVE, DEVICE_TOKEN_REVOKED |
The session or register is invalid: reconnect the register |
| 402, 403, 429 | NO_ACTIVE_BILLING, INSUFFICIENT_BALANCE, PAYMENT_BLOCKED, tariff limits |
A problem with the tariff, balance, or payment limit: «Тариф и баланс» |