xpayment вебхуктары: оқиғалар және қайталау

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 мекенжайын өзіңіз беруіңіз керек.

  1. Кабинетте Вебхуки (Вебхуктар) бөлімін ашып, + Новый вебхук (Жаңа вебхук) түймесін басыңыз.
  2. Дайын интеграцияны таңдаңыз немесе URL мен міндетті емес сипаттаманы (мысалы, Production webhook) қолмен енгізіңіз.
  3. Төлем және қайтарым оқиғаларын таңдаңыз. Интерфейсте алтауы бар; барлығын таңдау — қауіпсіз әдепкі нұсқа.
  4. Secret орнатыңыз: ұзын, кездейсоқ, бірегей жол. Өріс техникалық тұрғыда міндетті емес, бірақ secret-сіз қолтаңба қорғамайды: оны кез келген адам қайталай алады.
  5. Создать (Жасау) түймесін басып, байланысты Тест түймесімен тексеріңіз.

Жазылым жасалғаннан кейін бірден белсенді болады. Secret-ті құпиялар менеджерінде сақтаңыз: жазылымдар тізімі мен жаңартулар оны кейін қайтармайды.

Нақты төлемсіз тексеру

Байланысты алғаш тексеру үшін webhook.site сияқты уақытша қабылдағыш ыңғайлы. Өндірістік ортада ортақ тест мекенжайын және әлсіз secret қолданбаңыз.

Жазылымдарды API арқылы басқару

Жазылымдар кабинетте немесе 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 арқылы төленген брондау бойынша келеді.

Payload және тақырыптар

Барлық төлем және қайтарым оқиғалары бір конвертті қолданады:

{
  "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

Алған соң не істеу керек

  1. X-xPayment-Signature қолтаңбасын шикі дене бойынша тексеріңіз: Вебхук қолтаңбасын тексеру.
  2. delivery_id алыңыз (төмендегі «Идемпотентті өңдеу» бөлімін қараңыз).
  3. Төлемді сұраңыз: GET /v2/payments/{payment_id}. Сома, күй және metadata тек онда бар.
  4. Тапсырысты төлемнің нақты күйіне қарай орындаңыз.
  5. 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 мысалдары: Вебхук қолтаңбасын тексеру.

Байланысты нұсқаулықтар