Remote Payments via POST /v2/payments

How to invoice a buyer's phone through API v2: the request, idempotency, errors, code samples, and what the buyer sees in Kaspi.

What a phone invoice is

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.

When to use it

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.

What you need

  1. A connected register with an API name, for example Kassa1: Connecting a cash register and getting an API v2 key.
  2. An API v2 key xapi_….
  3. The buyer’s phone number, registered in Kaspi.
  4. A public webhook address to receive the result: xpayment webhooks.

How the process works

Your server -> POST /v2/payments -> xpayment -> invoice in Kaspi
                                                   |
                                         push to the buyer, payment
                                                   |
Your server <- payment.completed webhook <- xpayment <- new status
  1. Your server sends POST /v2/payments with device_name, the phone, and the amount.
  2. xpayment issues the invoice through Kaspi and returns the payment with status PENDING.
  3. The buyer receives a push, opens the invoice, and confirms payment.
  4. xpayment notices the new status (checks run every few seconds) and sends a webhook.
  5. Your server receives 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 is POST /v1/payments, the register is determined by the key, and the device_name field is not sent.

What the buyer sees

When you create an invoice through POST /v2/payments, this happens on the buyer’s side.

1. A push notification appears

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.

2. The invoice screen opens

Kaspi shows the invoice screen:

3. The buyer decides

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.


Important notes

The mockup below shows what the buyer sees on their phone:

API: creating a payment

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

Request fields

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.

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


Code samples

Node.js

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

Python

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

<?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);
}

Payment creation errors

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

The payment lifecycle

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

FAILED is not final. A payment with FAILED can later become COMPLETED: 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.

Cancellation

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.


Tracking the result

  1. A webhook is the main way. Get payment.completed, verify the signature, and fetch the payment: Webhooks, Signature verification.
  2. Polling is the fallback: GET /v2/payments/{payment_id} every 3–5 seconds until the status is final.
  3. The list is for reconciliation: GET /v2/payments?merchant_order_id=order-42.

Do not verify payment by screenshots or by the mere fact that an invoice was sent.