Төлемнің өмірлік циклі, FAILED күйі неге түпкілікті емес, төленбеген төлемді қалай тоқтатуға және толық не ішінара қайтарым жасауға болады.
Төлем жасау — жұмыстың жартысы ғана. Тапсырысты дұрыс орындау, төленбеген шотты тоқтату немесе ақшаны қайтару үшін төлемнің қандай күйлері бар екенін, қайсысы түпкілікті екенін және төлемнен кейін не болатынын түсіну керек. Бұл мақала API v2 үшін барлығын бір жерге жинайды.
Қысқаша:
PENDING → WAITING_FOR_PAYER → нәтижелердің біріне өтеді;COMPLETED, CANCELLED және EXPIRED нәтижелері түпкілікті;FAILED түпкілікті емес: осындай күйдегі төлем әлі COMPLETED бола алады;Күй туралы негізгі шындық көзі — төлемнің өзі: кез келген вебхуктан кейін 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 вебхугі сіздің жүйеңіз есептен шығарып қойған төлем бойынша келеді.
Сондықтан:
FAILED немесе payment.failed кейін тапсырыстан бас тартпаңыз және тауарды есептен шығармаңыз;FAILED күйін «әзірше төленбеген» деп санаңыз;COMPLETED, CANCELLED немесе EXPIRED. Бұл әрдайым төлемнің өмір сүру мерзімі ішінде болады: ең көбі бір тәулік.POST /v2/payments) 24 сағатқа дейін әрекет етеді; бұл Kaspi шектеуі.POST /v2/payments/link) айтарлықтай қысқа өмір сүреді: жауаптағы expire_date бойынша бағдарланыңыз.Нәтижені білудің негізгі жолы — вебхук (Вебхуктар, Қолтаңбаны тексеру). Қосалқы жолы — күй түпкілікті болғанша әр 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 |
жоқ | Қайтарым себебі |
COMPLETED және PARTIALLY_REFUNDED күйіндегі төлемдер үшін мүмкін. Басқаларына API 409 PAYMENT_NOT_REFUNDABLE қайтарады.PENDING күйімен 202 Accepted жауабы сұраныс қабылданғанын білдіреді, ақша қайтып келіп қойғанын емес.PARTIALLY_REFUNDED болады, соманың бәрі қайтарылғанда REFUNDED болады.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 өңдеуіңізді тексере аласыз.
202 жауабындағы refund_id сақтап, оны тапсырыспен салыстырыңыз: вебхукта ол болмайды.COMPLETED болғанда аяқталады.