POST /v2/payments арқылы қашықтан төлемдерді қабылдау

API v2 арқылы сатып алушының телефонына шотты қалай шығаруға болады: сұраныс, идемпотенттілік, қателер, код мысалдары және сатып алушы Kaspi-де не көреді.

Телефонға шот дегеніміз не

Телефонға шот (қашықтан төлем) — сатып алушының телефон нөмірі бойынша тікелей Kaspi қосымшасына жіберілетін төлем сұранысы. Сіз POST /v2/payments шақырасыз, xpayment шот шығарады, сатып алушы push-хабарлама алады, оны ашады және не төлейді, не бас тартады. Нәтижені вебхуктан білесіз.

Төлем сілтемесінен басты айырмашылығы: мұнда сатып алушының телефон нөмірі алдын ала қажет.

Қашан қолдану керек

Клиенттің нөмірі бұрыннан болса жарайды:

Нөмір болмаса немесе сатып алушы тапсырысты сайтта өзі рәсімдесе, төлем сілтемесін қолданыңыз. Сенімді емессіз бе? Нұсқаларды QR, deeplink немесе телефон нөмірі бойынша қашықтан төлем мақаласында салыстырыңыз.

Не қажет

  1. API атауы бар қосылған касса, мысалы, Kassa1: Кассаны қосу және API v2 кілті.
  2. API v2 кілті xapi_….
  3. Kaspi-де тіркелген сатып алушының телефон нөмірі.
  4. Нәтижені алу үшін вебхуктың ашық мекенжайы: xpayment вебхуктары.

Процесс қалай жұмыс істейді

Сіздің серверіңіз -> POST /v2/payments -> xpayment -> Kaspi-дегі шот
                                                   |
                                         сатып алушыға push, төлем
                                                   |
Сіздің серверіңіз <- payment.completed вебхугі <- xpayment <- жаңа күй
  1. Сіздің серверіңіз device_name, телефон және сомасымен POST /v2/payments жібереді.
  2. xpayment Kaspi арқылы шот шығарады және төлемді PENDING күйімен қайтарады.
  3. Сатып алушы push алады, шотты ашады және төлемді растайды.
  4. xpayment жаңа күйді байқайды (тексеру бірнеше секунд сайын жүреді) және вебхук жібереді.
  5. Сіздің серверіңіз payment.completed алады, GET /v2/payments/{payment_id} арқылы төлемді сұрайды және тапсырысты орындайды.

Касса кілтімен xdev_… API v1 әлі де қолдау табады: мекенжайы — POST /v1/payments, кассаны кілттің өзі анықтайды, device_name өрісі жіберілмейді.

Сатып алушы не көреді

POST /v2/payments арқылы шот шығарғанда, сатып алушы жағында мынадай жағдай болады.

1. Push-хабарлама пайда болады

Сатып алушы Kaspi қосымшасында push-хабарлама алады:

Kaspi.kz
ShopMebel дүкені сізге 50 000 ₸ шот шығарды

Хабарлама телефон құлыптаулы болса да, дерлік лезде келеді. Басқанда Kaspi қосымшасы ашылады.

2. Шот экраны ашылады

Kaspi шот экранын көрсетеді:

3. Сатып алушы шешім қабылдайды

«Төлеу» түймесін басады. Kaspi соманы таңдалған төлем тәсілінен есептен шығарады, сатып алушы растауды көреді. xpayment жаңа COMPLETED күйін бірнеше секунд ішінде байқайды, ал вебхугіңіз payment.completed алады.

Шоттан бас тартады немесе жауап бермейді. Төлем төленбейді. Kaspi мұны қалай хабарлағанына байланысты, ол CANCELLED, EXPIRED немесе уақытша FAILED күйіне өтеді, ал сіз сәйкес вебхук аласыз. Түйме атауына қарап болжамаңыз: GET /v2/payments/{payment_id} төлем күйіне сүйеніңіз. Сатып алушы ештеңе істемесе, төленбеген шот ең кеші 24 сағат ішінде мерзімі өтеді. Толығырақ: Төлем күйлері мен қайтарымдар.


Маңызды ескертулер

Төмендегі макет сатып алушының телефонында не көретінін көрсетеді:

API: төлем жасау

API v2 кілтімен және касса атауымен POST /v2/payments жіберіңіз:

curl -X POST https://api.xpayment.kz/v2/payments \
  -H "Authorization: Bearer xapi_СІЗДІҢ_КІЛТІҢІЗ" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-42-attempt-1" \
  -d '{
    "device_name": "Kassa1",
    "payer_phone": "+77001234567",
    "amount": 1500,
    "comment": "№42 тапсырыс",
    "merchant_order_id": "order-42",
    "metadata": {"product_id": "sku-999"}
  }'

Сұраныс өрістері

Өріс Түрі Міндетті Сипаттама
device_name string иә Касса атауы: латын әріптері мен сандар, 32 символға дейін, регистр маңызды емес
payer_phone string иә Сатып алушының нөмірі, мысалы, +77001234567
amount number иә Теңгемен сома, нөлден үлкен
comment string жоқ Сатып алушы Kaspi-де көретін хабарлама
merchant_order_id string жоқ Сіздің тапсырыс идентификаторыңыз. Вебхукта қайтып келеді
metadata object жоқ «Кілт-мән» пішіміндегі кез келген деректеріңіз, төлеммен бірге сақталады

X-Idempotency-Key тақырыбы міндетті емес, бірақ оны әрдайым жіберуді ұсынамыз: сол кілтпен қайталанған сұраныс бұрын жасалған төлемді қайтарады және екінші шот шығармайды. Кілтті басқа төлем ұстап тұрса, API 409 IDEMPOTENCY_CONFLICT жауап береді.

201 жауабы

{
  "payment_id": "018f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
  "device_name": "Kassa1",
  "payer_phone": "+77001234567",
  "amount": 1500.00,
  "currency": "KZT",
  "comment": "№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"
}

payment_id сақтаңыз: күйді сұрау, төлемді болдырмау және қайтарым жасау үшін оны қолданасыз.


Код мысалдары

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

Төлем жасау қателері

HTTP Код Себебі
400 VALIDATION_ERROR device_name, payer_phone немесе amount жоқ, нөмір пішімі қате немесе сома нөлден үлкен емес
401 — Кілт жіберілмеген, жойылған немесе API-дің басқа нұсқасына жатады
404 DEVICE_NOT_FOUND Осындай device_name бар белсенді касса жоқ
409 IDEMPOTENCY_CONFLICT Идемпотенттілік кілтін басқа төлем пайдаланған
422 KASPI_CLIENT_NOT_FOUND Kaspi мұндай сатып алушыны білмейді
422 KASPI_ERROR, DEVICE_INACTIVE, DEVICE_TOKEN_REVOKED Сессия немесе касса жарамсыз: кассаны қайта қосыңыз
402 NO_ACTIVE_BILLING, INSUFFICIENT_BALANCE Тариф белсенді емес немесе теңгерімде қаражат жеткіліксіз («Тариф и баланс»)
403 PAYMENT_BLOCKED Ұйымыңыз үшін төлем қабылдау бұғатталған. «Тариф и баланс» бөлімін тексеріңіз немесе қолдау қызметіне жазыңыз
429 DAILY_TX_LIMIT_REACHED, MONTHLY_PAYMENT_LIMIT_REACHED Тарифтің күндік немесе айлық төлем лимиті таусылды
500 INTERNAL_ERROR Күтпеген қате. Сол X-Idempotency-Key кілтімен қайталаңыз

Төлемнің өмірлік циклі

Төлем алдымен PENDING, содан кейін WAITING_FOR_PAYER (сатып алушы шотты көрді) күйінде болады және нәтижелердің біріне келеді:

Күй Нені білдіреді Болдырмауға бола ма?
PENDING, WAITING_FOR_PAYER Шот жасалды, сатып алушыны күтуде Иә
COMPLETED Сатып алушы төледі Жоқ, қайтарым жасаңыз
CANCELLED Төлем тоқтатылды Жоқ
EXPIRED Уақыт өтті немесе сатып алушы растамады Жоқ
FAILED Kaspi төлемді қабылдамады немесе түсініксіз жауап берді Иә, төлем әлі аяқталуы мүмкін

FAILED түпкілікті емес. FAILED күйіндегі төлем кейін COMPLETED бола алады: xpayment оның өмір сүру мерзімі аяқталғанша тексеруді жалғастырады. Мұндай тапсырысты бірден есептен шығармаңыз. Күйлер, бас тарту және қайтарымдар туралы толық талдау: Төлем күйлері мен қайтарымдар.

Бас тарту

curl -X POST https://api.xpayment.kz/v2/payments/PAYMENT_ID/cancel \
  -H "Authorization: Bearer xapi_СІЗДІҢ_КІЛТІҢІЗ" \
  -H "Content-Type: application/json" \
  -d '{"reason": "Клиент ойын өзгертті"}'

Төлем аяқталған болса, жауап — 409 PAYMENT_NOT_CANCELABLE.


Нәтижені қадағалау

  1. Вебхук — негізгі тәсіл. payment.completed алыңыз, қолтаңбаны тексеріңіз және төлемді сұраңыз: Вебхуктар, Қолтаңбаны тексеру.
  2. Сұрау — қосалқы нұсқа: күй түпкілікті болғанша GET /v2/payments/{payment_id} әр 3–5 секунд сайын.
  3. Тізім — салыстыру үшін: GET /v2/payments?merchant_order_id=order-42.

Төлемді скриншоттармен немесе шот жіберілгенінің өзімен тексермеңіз.