xpayment вебхуктарын баптаңыз: алты төлем және қайтарым оқиғасы, payload пішімі, қайталау, идемпотенттілік және қолтаңбаны тексеру.
Вебхук — төлем немесе қайтарым маңызды күйге өткенде xpayment сіздің серверіңізге жіберетін HTTP POST сұранысы. Сіздің өңдеушіңіз API-ді үнемі сұрамай-ақ тапсырысты растай, резервті алып тастай немесе қайтарымды есепке ала алады.
Телефонға шоттар, төлем сілтемелері және кабинеттегі төлемдер үшін ағын бірдей:
Сіздің серверіңіз -> xpayment -> Kaspi
|
күй өзгерді
v
Сіздің серверіңіз <- вебхук <- xpayment
Вебхук жазылымдары ұйым үшін ортақ: оқиғалар API v2, API v1 және кабинет арқылы жасалған төлемдер бойынша келеді, сондықтан әр тәсілге бөлек жазылым қажет емес.
xpayment күтіп тұрған төлемдер мен QR-токендерді фондық процестермен әр 5 секунд сайын тексереді, ал вебхук кезегі әр 2 секунд сайын қаралады. Бұл — іске қосу аралықтары, кепілдік берілген жеткізу мерзімі емес: оған Kaspi жауабы, жүктеме және желі де әсер етеді.
Вебхуктарды негізгі хабарлама арнасы ретінде қолданыңыз. GET /v2/payments/{payment_id} салыстыру үшін және өңдеушіңіз қолжетімсіз болғаннан кейін қалпына келтіру үшін пайдалы.
Вебхукта сома да, күй де жоқ. Ол тек сол төлеммен оқиға болғанын хабарлайды. Оны алған соң, төлемді
GET /v2/payments/{payment_id}арқылы сұраңыз және оның күйіне сүйеніңіз.
xpayment аккаунты және өңдеушіңіздің ашық мекенжайы қажет. Өндірістік ортада тек HTTPS қолданыңыз. API қазір мекенжайдың бос емес екенін ғана тексереді, сондықтан дұрыс әрі қолжетімді HTTPS мекенжайын өзіңіз беруіңіз керек.
Production webhook) қолмен енгізіңіз.Жазылым жасалғаннан кейін бірден белсенді болады. Secret-ті құпиялар менеджерінде сақтаңыз: жазылымдар тізімі мен жаңартулар оны кейін қайтармайды.
payment.completed мысалын жібереді. Ол байланысты тексереді, бірақ жеткізу тарихына жазылмайды және қайталанбайды. 2xx емес жауап тестті бірден сәтсіз аяқтайды.POST /v2/webhook-simulate нақты төлемсіз жазылымдарыңызға тест payment.* оқиғасын жібереді. Жазылымдарыңыздың тізімі: GET /v2/webhook-simulate/subscriptions.Байланысты алғаш тексеру үшін webhook.site сияқты уақытша қабылдағыш ыңғайлы. Өндірістік ортада ортақ тест мекенжайын және әлсіз secret қолданбаңыз.
Жазылымдар кабинетте немесе xusr_pat_… жеке токенімен POST /v1/webhooks арқылы жасалады (ол API-ключи (API кілттері) → «Личные токены» (Жеке токендер) бөлімінде шығарылады). xapi_… кілті жазылымдарды басқара алмайды: ол төлемдерге арналған. Сұраныс денесі: url, events, secret, description.
«Вебхуки» (Вебхуктар) бөлімінде алты төлем және қайтарым оқиғасы бар:
| Оқиға | Шарт | Ұсынылатын әрекет |
|---|---|---|
payment.completed |
Төлем COMPLETED күйін алды |
Тапсырысты бір рет орындау |
payment.expired |
Kaspi CancelledByUser, Expired қайтарды немесе QR-токеннің мерзімі өтті не тасталды |
Резервті алып тастап, жаңа төлемді ұсыну |
payment.cancelled |
Төлем POST /v2/payments/{payment_id}/cancel арқылы болдырылмады немесе Kaspi Cancelled қайтарды |
Резервті алып тастау |
payment.failed |
Төлем қате күйіне өтті (төменде қараңыз: ол түпкілікті емес) | Қатені жазу, тапсырысты бірден есептен шығармау және сатып алушыға жаңа әрекет ұсыну |
payment.refunded |
Толық немесе ішінара қайтарым POST /v2/payments/{payment_id}/refund арқылы аяқталды |
Тапсырысты payment_id бойынша салыстыру |
payment.refund_failed |
Қайтарымды аяқтау мүмкін болмады | Төлемді тексеруге беру |
* жазылымы барлық оқиғаны алады.
Вебхук денесі әдейі шағын. Қайтарым оқиғаларында refund_id, қайтарым сомасы және қате себебі жоқ: payment_id-ді өз жазбаңызбен салыстырыңыз немесе төлемнің қайтарымдарын GET /v2/payments/{payment_id}/refunds арқылы сұраңыз.
Сатып алушының әрекетін тек оқиға атауына қарап болжамаңыз. Мысалы, Kaspi CancelledByUser деп жіберетін бас тарту payment.expired болып шығады, ал payment.cancelled — айқын болдырмау немесе Kaspi-дің Cancelled күйі.
payment.failed— оқиғаның соңы емес.FAILEDкүйіндегі төлем Kaspi кейін төлемді растаса,COMPLETEDболып аяқталуы мүмкін. Төлем түпкілікті күйге жеткеншеGET /v2/payments/{payment_id}арқылы тексеріңіз. Толығырақ: Төлем күйлері мен қайтарымдар.
Төлемі бар онлайн жазылуды қолдансаңыз, booking.* жеке оқиғалары бар; олар тек Kaspi арқылы төленген брондау бойынша келеді.
Барлық төлем және қайтарым оқиғалары бір конвертті қолданады:
{
"event": "payment.completed",
"event_version": "1",
"delivery_id": "c09a3647-7822-4899-8401-3857cbd5bf68",
"attempt_number": 1,
"source": "xpayment",
"payment_id": "65cd0d84-5f66-4763-94d2-1b8e1ba68347",
"merchant_order_id": "order-5512",
"created_at": "2026-11-08T10:32:00+05:00",
"environment": "live"
}
| Өріс | Мәні |
|---|---|
event |
Оқиға түрі |
event_version |
Payload схемасының нұсқасы; қазір 1 |
delivery_id |
Қайталауларда өзгермейтін осы жеткізудің ID-і |
attempt_number |
1-ден басталады және әр қайталауда артады |
source |
Әрдайым xpayment |
payment_id |
xpayment-тегі байланысты төлем ID-і |
merchant_order_id |
Сіздің тапсырыс ID-іңіз; берілмесе, жоқ |
created_at |
Оқиға кезекке қойылған уақыт (ISO 8601) |
environment |
Боевой төлемдер үшін live, тест төлемдері үшін sandbox |
Екі тақырыпқа сүйеніңіз:
Content-Type: application/json
X-xPayment-Signature: aeafc0dcd86de4d4d376f525be2b1175520c2818c93938ec8d069957c63a373b
X-xPayment-Signature қолтаңбасын шикі дене бойынша тексеріңіз: Вебхук қолтаңбасын тексеру.delivery_id алыңыз (төмендегі «Идемпотентті өңдеу» бөлімін қараңыз).GET /v2/payments/{payment_id}. Сома, күй және metadata тек онда бар.2xx жауап беріңіз.xpayment кез келген 2xx жауабын сәтті деп санайды. Желі қатесі, 10 секундтық тайм-аут немесе түпкілікті 2xx емес жауап қайталауға әкеледі. Барлығы ең көбі үш әрекет: бірден, бірінші сәтсіздіктен кейін шамамен 1 минуттан және екіншісінен кейін шамамен 5 минуттан соң.
Қайталауларда delivery_id өзгермейді, ал attempt_number артады, сондықтан JSON және оның қолтаңбасы өзгереді. Оқиғаларды жеткізу реті кепілдендірілмейді. 2xx-ті оқиғаны сенімді қабылдағаннан кейін ғана қайтарыңыз, ал xpayment жеткізуді қайталауын қаласаңыз, 2xx емес жауап қайтарыңыз.
delivery_id бойынша бірегей шектеу қосып, оны бизнес-өзгеріспен бір транзакцияда жазыңыз. Бұл TypeScript мысалында орындау сәтсіз болса, екі операция да кері қайтады:
await db.transaction(async (tx) => {
const accepted = await tx.webhookReceipts.insertIfAbsent(payload.delivery_id)
if (!accepted) return // бұрын қабылданған, қайта жауап береміз
const payment = await xpayment.getPayment(payload.payment_id) // GET /v2/payments/{id}
if (payment.status === "COMPLETED") {
await tx.orders.markPaid(payload.merchant_order_id, payload.payment_id)
}
})
return res.status(200).json({ ok: true })
Тапсырысты орындау сыртқы сервисті шақырса, тапсырманы сол транзакцияда сақтап (outbox), оны асинхронды орындаңыз. Бір мекенжай бірнеше жазылымда көрсетілсе, (payment_id, event) жұбы бойынша бір реттік орындауды да қамтамасыз етіңіз: әр жазылымның өз delivery_id мәні бар.
«Вебхуки» бөлімінде соңғы жеткізулерді көру үшін жазылымды ашыңыз. API арқылы олар жеке токенмен GET /v1/webhooks/{subscriptionID}/deliveries мекенжайында қолжетімді. Жеткізу күйлері: PENDING, SUCCESS, FAILED және EXHAUSTED; соңғы сәтсіз әрекеттен кейін жеткізу EXHAUSTED алады. Тарихты диагностика үшін қолданыңыз, өз жүйеңіздегі салыстырудың орнына емес.
Талдау және өңдеу алдында X-xPayment-Signature қолтаңбасын дененің нақты байттары мен жазылым secret-і бойынша тексеріңіз. Алгоритм және Node.js, Go, Python мысалдары: Вебхук қолтаңбасын тексеру.