API v2 төлем күйлері, бас тарту және қайтарым

Төлемнің өмірлік циклі, FAILED күйі неге түпкілікті емес, төленбеген төлемді қалай тоқтатуға және толық не ішінара қайтарым жасауға болады.

Күйлер мен қайтарымдар туралы не білу керек

Төлем жасау — жұмыстың жартысы ғана. Тапсырысты дұрыс орындау, төленбеген шотты тоқтату немесе ақшаны қайтару үшін төлемнің қандай күйлері бар екенін, қайсысы түпкілікті екенін және төлемнен кейін не болатынын түсіну керек. Бұл мақала API v2 үшін барлығын бір жерге жинайды.

Қысқаша:

Күй туралы негізгі шындық көзі — төлемнің өзі: кез келген вебхуктан кейін GET /v2/payments/{payment_id} сұраңыз. Вебхуктар туралы толығырақ: xpayment вебхуктары.

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

PENDING
  └─► WAITING_FOR_PAYER   (сатып алушы шотты немесе сілтемені ашты)
        ├─► COMPLETED          (сатып алушы төледі)
        ├─► CANCELLED          (сіз немесе Kaspi тоқтатты)
        └─► EXPIRED            (уақыт өтті немесе сатып алушы растамады)
  └─► CANCELLING          (тоқтату сұралды, Kaspi растауын күтеміз)
  └─► FAILED              (әзірше түпкілікті емес, төменде қараңыз)
        ├─► COMPLETED          (Kaspi кейін төлемді растады)
        ├─► CANCELLED / EXPIRED
        └─► FAILED             (төлем мерзімі өткенде FAILED болып қалады)

COMPLETED
  └─► PARTIALLY_REFUNDED  (кемінде бір қайтарым аяқталды)
  └─► REFUNDED            (соманың бәрі қайтарылды)
Күй Нені білдіреді Түпкілікті ме?
PENDING Төлем жасалды, күтуде Жоқ
WAITING_FOR_PAYER Сатып алушы шотты көріп отыр немесе сілтемені ашты Жоқ
CANCELLING Тоқтатуды сұрадыңыз, Kaspi әлі растаған жоқ Жоқ
COMPLETED Сатып алушы төледі Иә (қайтарымдар әлі мүмкін)
CANCELLED Төлем тоқтатылды Иә
EXPIRED Уақыт өтті немесе сатып алушы растамады Иә
FAILED Kaspi төлемді қабылдамады немесе түсініксіз жауап берді Жоқ
PARTIALLY_REFUNDED Соманың бір бөлігі қайтарылды Төлем бойынша есеп айырысу аяқталды
REFUNDED Соманың бәрі қайтарылды Иә

Тізімдердегі status сүзгісі үшін жауаптағыдай бас әріптерді қолданыңыз (completed емес, COMPLETED).

FAILED неге соңы емес

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

Сондықтан:

Төлем қанша тұрады

Вебхук немесе сұрау

Нәтижені білудің негізгі жолы — вебхук (Вебхуктар, Қолтаңбаны тексеру). Қосалқы жолы — күй түпкілікті болғанша әр 3–5 секунд сайын GET /v2/payments/{payment_id} сұрау:

import os, time
import httpx

API = "https://api.xpayment.kz/v2"
HEADERS = {"Authorization": f"Bearer {os.environ['XPAYMENT_API_KEY']}"}
# FAILED әдейі жоқ: ол қайтымды.
FINAL = {"COMPLETED", "CANCELLED", "EXPIRED", "REFUNDED"}


def wait_for_payment(payment_id: str, timeout_sec: int = 120) -> dict:
    deadline = time.time() + timeout_sec
    while time.time() < deadline:
        resp = httpx.get(f"{API}/payments/{payment_id}", headers=HEADERS, timeout=15)
        resp.raise_for_status()
        payment = resp.json()
        if payment["status"] in FINAL:
            return payment
        time.sleep(4)
    raise TimeoutError(f"payment {payment_id} did not reach a final status in {timeout_sec}s")

Төлемдер тізімі

GET /v2/payments төлемдерді курсормен беттеп (20-дан) қайтарады. Сүзгілер: status, payer_phone, merchant_order_id, device_name (регистр маңызды емес, осы атаулы бұрынғы кассалардың төлемдерін қамтиды) және cursor.

curl "https://api.xpayment.kz/v2/payments?status=COMPLETED&device_name=Kassa1" \
  -H "Authorization: Bearer xapi_СІЗДІҢ_КІЛТІҢІЗ"
{
  "data": [ /* төлемдер */ ],
  "has_more": true,
  "next_cursor": "MjAyNi0xMS0wN1QxMDowMDowMFp8dXVpZA=="
}

has_more мәні true болғанша, next_cursor мәнін cursor параметріне беріңіз.

Төлемді тоқтату

Төленбеген төлемді тоқтатуға болады: мысалы, клиент ойын өзгертті немесе сіз тапсырысты ауыстырдыңыз.

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

reason өрісі міндетті емес. 200 жауабында CANCELLING (Kaspi растауын күтеміз) немесе бірден CANCELLED күйіндегі жаңартылған төлем болады; нәтиже payment.cancelled вебхугімен келеді.

Төлем аяқталмағанша тоқтатуға болады: PENDING, WAITING_FOR_PAYER және тіпті FAILED күйінде (ол әлі бақылауда, өйткені төленуі мүмкін). Төлемнің нәтижесі белгілі болғанда, тоқтату 409 PAYMENT_NOT_CANCELABLE қайтарады.

Бұл жарыс жағдайына да қатысты: сатып алушы сіздің оқуыңыз бен тоқтату сұранысыңыздың арасында төлеп үлгерсе, төлем фактісі жеңеді, ал тоқтату қабылданбайды. Мұндай жағдайда ақша жеке қайтарыммен қайтарылады (келесі бөлім).

Сол merchant_order_id үшін жаңа сілтеме жасасаңыз, бұрынғы төленбеген сілтемелер автоматты түрде және вебхуксіз тоқтатылады. Толығырақ: Төлем сілтемелері.

Қайтарымдар

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

curl -X POST https://api.xpayment.kz/v2/payments/PAYMENT_ID/refund \
  -H "Authorization: Bearer xapi_СІЗДІҢ_КІЛТІҢІЗ" \
  -H "Content-Type: application/json" \
  -d '{"amount": 500, "reason": "Тауар қайтарылды"}'
Өріс Міндетті Сипаттама
amount иә Нөлден үлкен және әлі қайтаруға болатын қалдықтан аспайды
reason жоқ Қайтарым себебі

Нені білу керек

202 жауабы

{
  "refund_id": "2a7c0f6e-6c87-4d0d-8a5a-0d6f4a3b9c11",
  "payment_id": "018f1a2b-3c4d-5e6f-7a8b-9c0d1e2f3a4b",
  "amount": 500.00,
  "reason": "Тауар қайтарылды",
  "status": "PENDING",
  "fail_reason": null,
  "created_at": "2026-11-08T10:05:00Z",
  "updated_at": "2026-11-08T10:05:00Z",
  "completed_at": null
}

Қайтарым күйлері

PENDING → PROCESSING → COMPLETED немесе FAILED. Соңғы екеуі түпкілікті. Қайтарым сәтсіз болса, fail_reason өрісінде себебі көрсетіледі.

Күй Нені білдіреді
PENDING Қайтарым қабылданды және өңдеуді күтуде
PROCESSING Қайтарым орындалып жатыр
COMPLETED Ақша сатып алушыға қайтты
FAILED Қайтарымды орындау мүмкін болмады

Нәтижені қалай білу керек

Вебхуктар: payment.refunded (қайтарым аяқталды) және payment.refund_failed (сәтсіз болды). Оларда refund_id мен қайтарым сомасы жоқ, сондықтан API арқылы салыстырыңыз:

Сұраныс Не қайтарады
GET /v2/payments/{payment_id}/refunds Бір төлемнің қайтарымдары
GET /v2/refunds Барлық қайтарымдар, payment_id, status және cursor сүзгілері
GET /v2/refunds/{refundID} Бір қайтарым

Вебхуктар туралы толығырақ: xpayment вебхуктары. Қайтарымдарды нақты ақшасыз sandbox-та байқап көруге болады: дәл 13.13 ₸ қайтарым онда әрдайым қабылданбайды, сондықтан payment.refund_failed өңдеуіңізді тексере аласыз.

Практикалық кеңестер