Payment Links via POST /v2/payments/link

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.

What a payment link is

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”.

The key difference: the buyer’s phone is not needed

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.

When to use it

Payment links fit when:

A phone invoice is better when:

If there is no developer, you can create the same links in the dashboard without code: Accept payments without coding.

How it works: a 30-second path

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
  1. Your server sends POST /v2/payments/link with device_name, amount, and (preferably) merchant_order_id.
  2. xpayment creates a Kaspi QR and returns qr_token, payment_id, and expire_date.
  3. You show qr_token as a QR or a button.
  4. The buyer pays in the Kaspi app.
  5. xpayment sends the payment.completed webhook, and you fulfill the order.

What you need to start

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

What happens behind the scenes

API v1: the same flow through POST /v1/payments/link with a register key xdev_… (without device_name). It is still supported.

What the buyer sees

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:

The buyer’s path: from tap to payment

1. The buyer receives the link

The link can arrive any way:

2. The buyer taps the link

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.

3. The buyer confirms the payment

Tapping Pay starts the transaction: Kaspi charges the amount, the buyer sees a confirmation and gets an electronic receipt.

4. Your server learns about the payment

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.


What if the buyer does not have the Kaspi app?

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_date field of the response, usually a few minutes. If the buyer did not make it in time, create a new link.


API: creating a payment link

Request

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

Response 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

How to show the link to the buyer

Option 1: a button on a website (recommended)

<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.

Option 2: a QR on a computer screen

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.

Option 3: a WhatsApp or Telegram message

Send qr_token as text: Pay for order #42: https://qr.kaspi.kz/…. The link is clickable and opens Kaspi.

A TypeScript example

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 }
}

A Python example

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()

Expiry and re-creation

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 by merchant_order_id.


Tracking the status

Statuses and refund rules: Payment statuses and refunds.

Errors

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: «Тариф и баланс»