How to choose a Kaspi Pay payment flow in xpayment: a payment link with QR or deeplink, an invoice to a phone number, or the no-code tools in the dashboard.
xpayment offers several practical ways to accept Kaspi Pay payments: a payment link (QR or deeplink), an invoice to the customer’s phone, and ready-made dashboard tools that need no code. All of them work through your cash register and end the same way: with a webhook or a record in the dashboard.
xpayment.kz provides the API layer: your product creates a payment with an API v2 request, xpayment links it to Kaspi Pay, and then reports by webhook when the status changes. This article is not for copying examples but for choosing the right user path.
| Situation | What to choose | Why |
|---|---|---|
| The buyer is on a desktop or laptop | QR | It is easy to scan a QR with a phone |
| The buyer is already on a smartphone | Deeplink or a pay button | Scanning a QR from the same phone is awkward |
| You know the customer’s Kaspi number | Phone invoice | The customer gets a payment request right in Kaspi |
| A CRM invoices a regular customer | Phone invoice | The manager or system already knows the number |
| A Telegram bot sells a digital product | Deeplink or phone invoice | Depends on whether the bot collected a number |
| There is no developer | A payment link from the dashboard | Created with a wizard, no code: Accept payments without coding |
| n8n automates invoices | Both API options | A link suits messages, a phone invoice suits CRM customers |
On the Kaspi Pay page, Kaspi describes several ways to accept payments: a mobile POS with a QR for each purchase, a QR at the till, remote payment, and a payment link.
For an integration through xpayment they become two API models and one dashboard tool:
POST /v2/payments/link: you create a link or QR for a specific amount.POST /v2/payments: you send a payment request to the buyer’s phone number.In both API requests you name the register by device_name (for example Kassa1) and sign with an xapi_… key.
Use a payment link when the customer opens the payment on their own. It is the right choice for a checkout, a bot, a landing page, a message, or any self-service flow.
Within one flow you can give the user two ways in:
The link is short-lived: the lifetime is in the expire_date field of the response, usually a few minutes. If the buyer did not make it, create a new one.
Full examples: Payment links via POST /v2/payments/link.
A QR suits cases where the buyer sees the order on a big screen:
The buyer scans the QR with a phone, opens Kaspi, and confirms the payment.
A deeplink is more convenient when the buyer is already on a phone:
Asking a user to scan a QR code shown on the same phone is pointless: they need a button or a link.
Use this flow when your product already knows the customer’s phone number. A system or manager does not wait for the customer to open a checkout and sends the invoice straight to the Kaspi app.
Kaspi Guide describes the manual remote payment like this: a cashier or manager chooses remote payment, enters the customer’s number and amount, and sends the invoice. Source: How do I issue an invoice remotely? Through xpayment this logic becomes an API call: instead of typing in the app, your backend or n8n workflow sends the request automatically.
Full implementation: Remote payments via POST /v2/payments.
If you simply need to accept payments and have no developer, the dashboard has ready tools: payment links with a form, online booking with a prepayment, and recurring payments on a schedule. They use the same registers and show payments in the Транзакции (Transactions) section. More: Accept payments without coding.
If you accept payments through a permanent (static) QR and want to reconcile them on your side, use GET /v2/static-qr-payments/{orderNumber}: it finds a payment by the order number from Kaspi’s history. This request is not available in the sandbox.
| Product | Best way | Why |
|---|---|---|
| An online store checkout on a computer | QR (payment link) | The buyer scans the screen with a phone |
| A mobile checkout | Deeplink | The buyer is already on the phone |
| A Telegram bot without a phone number | Deeplink | The bot sends a pay button |
| A Telegram bot with a phone number | Phone invoice | You can send the request to Kaspi right away |
| A CRM for managers | Phone invoice | The customer’s number is usually there |
| Delivery with a final amount | Phone invoice | The amount appears after the order is assembled |
| A SaaS subscription | A phone invoice or a link; plans and access — subscriptions API | Depends on whether the customer’s number is known |
| A small business without a developer | A payment link from the dashboard | A wizard, templates, and a payment list |
| n8n | Any | The HTTP Request node can call any endpoint |
Do not mark an order as paid right after creating a payment. Creating a payment only means a way to pay was shown or sent to the customer. The payment.completed webhook confirms payment, and after it you fetch the payment: GET /v2/payments/{payment_id}. More: xpayment webhooks and Payment statuses and refunds.
If the checkout is open on a smartphone, show a pay button, not a QR.
The user must understand why they leave a number and that they will get a payment request in Kaspi.
merchant_order_idWithout your order ID it is harder to link a payment, a webhook, and an order in your system. Always pass it.
If your backend repeats a request after a timeout, a duplicate can be created. For POST /v2/payments, send the X-Idempotency-Key header.
A screenshot does not confirm a payment. Confirmation is a webhook and a status check through the API.
For testing flows there is the sandbox: a test register, test keys, and simulated outcomes without charging money.