How to invoice a buyer's phone through API v2: the request, idempotency, errors, code samples, and what the buyer sees in Kaspi.
A phone invoice (a remote payment) is a payment request sent to the buyer straight into the Kaspi app by their phone number. You call POST /v2/payments, xpayment issues the invoice, the buyer receives a push notification, opens it, and either pays or declines. You learn the result from a webhook.
The main difference from a payment link: here you need the buyer’s phone number in advance.
It fits when you already have the customer’s number:
If there is no number or the buyer places the order on the website themselves, use a payment link. Not sure? Compare the options in QR, deeplink, or remote phone payment.
Kassa1: Connecting a cash register and getting an API v2 key.xapi_….Your server -> POST /v2/payments -> xpayment -> invoice in Kaspi
|
push to the buyer, payment
|
Your server <- payment.completed webhook <- xpayment <- new status
POST /v2/payments with device_name, the phone, and the amount.PENDING.payment.completed, fetches the payment with GET /v2/payments/{payment_id}, and fulfills the order.API v1 with a register key
xdev_…is still supported: the address isPOST /v1/payments, the register is determined by the key, and thedevice_namefield is not sent.
When you create an invoice through POST /v2/payments, this happens on the buyer’s side.
The buyer receives a push notification in the Kaspi app:
Kaspi.kz
The store ShopMebel has invoiced you 50 000 ₸
The notification arrives almost instantly, even if the phone is locked. Tapping it opens the Kaspi app.
Kaspi shows the invoice screen:
comment field from your request;Taps “Pay”. Kaspi charges the amount to the chosen payment method, and the buyer sees a confirmation. xpayment notices the new COMPLETED status within a few seconds, and your webhook receives payment.completed.
Declines the invoice or does not respond. The payment will not be paid. Depending on how Kaspi reports it, it will move to CANCELLED, EXPIRED, or temporarily FAILED, and you get the matching webhook. Do not try to guess from the button name: rely on the payment status from GET /v2/payments/{payment_id}. If the buyer does nothing, an unpaid invoice expires within 24 hours at the latest. More: Payment statuses and refunds.
+77001234567, 87001234567, and 7001234567, and Kaspi must know that number. If no customer with that number is found, you get the error 422 KASPI_CLIENT_NOT_FOUND.POST /v2/payments/{payment_id}/cancel.The mockup below shows what the buyer sees on their phone:
Send POST /v2/payments with an API v2 key and the register name:
curl -X POST https://api.xpayment.kz/v2/payments \
-H "Authorization: Bearer xapi_YOUR_KEY" \
-H "Content-Type: application/json" \
-H "X-Idempotency-Key: order-42-attempt-1" \
-d '{
"device_name": "Kassa1",
"payer_phone": "+77001234567",
"amount": 1500,
"comment": "Order #42",
"merchant_order_id": "order-42",
"metadata": {"product_id": "sku-999"}
}'
| Field | Type | Required | Description |
|---|---|---|---|
device_name |
string | yes | The register name: Latin letters and digits, up to 32 characters, case-insensitive |
payer_phone |
string | yes | The buyer’s number, for example +77001234567 |
amount |
number | yes | The amount in tenge, greater than zero |
comment |
string | no | A message the buyer sees in Kaspi |
merchant_order_id |
string | no | Your order identifier. It comes back in the webhook |
metadata |
object | no | Any of your data as key-value pairs, stored with the payment |
The X-Idempotency-Key header is optional, but we advise sending it always: a repeated request with the same key returns the payment that was already created and does not issue a second invoice. If the key is already held by another payment, the API answers 409 IDEMPOTENCY_CONFLICT.
201{
"payment_id": "018f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
"device_name": "Kassa1",
"payer_phone": "+77001234567",
"amount": 1500.00,
"currency": "KZT",
"comment": "Order #42",
"merchant_order_id": "order-42",
"status": "PENDING",
"metadata": {"product_id": "sku-999"},
"cancel_reason": null,
"cancelled_at": null,
"completed_at": null,
"created_at": "2026-11-08T10:00:00Z",
"updated_at": "2026-11-08T10:00:00Z"
}
Save the payment_id: you will use it to request the status, cancel the payment, and make a refund.
async function createInvoice({ phone, amount, orderId }) {
const res = await fetch("https://api.xpayment.kz/v2/payments", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.XPAYMENT_API_KEY}`,
"Content-Type": "application/json",
"X-Idempotency-Key": `invoice-${orderId}`,
},
body: JSON.stringify({
device_name: process.env.XPAYMENT_DEVICE_NAME,
payer_phone: phone,
amount,
merchant_order_id: orderId,
}),
})
if (res.status !== 201) throw new Error(`xpayment ${res.status}: ${await res.text()}`)
return res.json()
}
import os
import httpx
def create_invoice(phone: str, amount: float, order_id: str) -> dict:
resp = httpx.post(
"https://api.xpayment.kz/v2/payments",
headers={
"Authorization": f"Bearer {os.environ['XPAYMENT_API_KEY']}",
"X-Idempotency-Key": f"invoice-{order_id}",
},
json={
"device_name": os.environ["XPAYMENT_DEVICE_NAME"],
"payer_phone": phone,
"amount": amount,
"merchant_order_id": order_id,
},
timeout=15,
)
resp.raise_for_status()
return resp.json()
<?php
function createInvoice(string $phone, float $amount, string $orderId): array
{
$ch = curl_init('https://api.xpayment.kz/v2/payments');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . getenv('XPAYMENT_API_KEY'),
'Content-Type: application/json',
'X-Idempotency-Key: invoice-' . $orderId,
],
CURLOPT_POSTFIELDS => json_encode([
'device_name' => getenv('XPAYMENT_DEVICE_NAME'),
'payer_phone' => $phone,
'amount' => $amount,
'merchant_order_id' => $orderId,
]),
]);
$body = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
if ($status !== 201) {
throw new RuntimeException("xpayment $status: $body");
}
return json_decode($body, true);
}
| HTTP | Code | Cause |
|---|---|---|
| 400 | VALIDATION_ERROR |
device_name, payer_phone, or amount is missing, the number format is wrong, or the amount is not greater than zero |
| 401 | — | The key is missing, revoked, or belongs to another API version |
| 404 | DEVICE_NOT_FOUND |
There is no active register with this device_name |
| 409 | IDEMPOTENCY_CONFLICT |
The idempotency key is already used by another payment |
| 422 | KASPI_CLIENT_NOT_FOUND |
Kaspi does not know this buyer |
| 422 | KASPI_ERROR, DEVICE_INACTIVE, DEVICE_TOKEN_REVOKED |
The session or register is invalid: reconnect the register |
| 402 | NO_ACTIVE_BILLING, INSUFFICIENT_BALANCE |
The tariff is not active or the balance is too low («Тариф и баланс») |
| 403 | PAYMENT_BLOCKED |
Accepting payments is blocked for your organization. Check «Тариф и баланс» or contact support |
| 429 | DAILY_TX_LIMIT_REACHED, MONTHLY_PAYMENT_LIMIT_REACHED |
The tariff’s daily or monthly payment limit is exhausted |
| 500 | INTERNAL_ERROR |
An unexpected error. Retry with the same X-Idempotency-Key |
A payment is first PENDING, then WAITING_FOR_PAYER (the buyer saw the invoice), and arrives at one of the outcomes:
| Status | What it means | Can it be cancelled? |
|---|---|---|
PENDING, WAITING_FOR_PAYER |
The invoice is created and waits for the buyer | Yes |
COMPLETED |
The buyer paid | No, make a refund |
CANCELLED |
The invoice is cancelled | No |
EXPIRED |
Time ran out or the buyer did not confirm | No |
FAILED |
Kaspi rejected the payment or answered unclearly | Yes, the payment can still complete |
FAILEDis not final. A payment withFAILEDcan later becomeCOMPLETED: xpayment keeps checking it until its lifetime is over. Do not write such an order off at once. A detailed look at statuses, cancellation, and refunds: Payment statuses and refunds.
curl -X POST https://api.xpayment.kz/v2/payments/PAYMENT_ID/cancel \
-H "Authorization: Bearer xapi_YOUR_KEY" \
-H "Content-Type: application/json" \
-d '{"reason": "The customer changed their mind"}'
If the payment is already settled, the answer is 409 PAYMENT_NOT_CANCELABLE.
payment.completed, verify the signature, and fetch the payment: Webhooks, Signature verification.GET /v2/payments/{payment_id} every 3–5 seconds until the status is final.GET /v2/payments?merchant_order_id=order-42.Do not verify payment by screenshots or by the mere fact that an invoice was sent.