Вебхуктар: оқиғалар, қолтаңбалар және жеткізу

Оқиғалар қайдан келеді#

invoice.created төленді дегенді білдірмейді. Төлем оқиғалары ағымдағы шлюз оқуынан кейін расталған сервер операциясынан келеді; кірген оқиға атауы жалғыз өзі жеткіліксіз.

Шлюз → Kevmi кіруі және Kevmi → саудагер жеткізуі жеке құпиялармен әртүрлі кезеңдер болып табылады. Браузер, қайта бағыттау және виджет хабарламалары қаржылық күйді орнатпайды.

Нүктені тіркеу және растау#

URL мекенжайлары IP мекенжайларға, localhost-қа, жеке желілерге, стандартты емес порттарға бағытталмауы немесе тіркелгі деректерін қамтымауы керек. DNS жеткізу алдында тексеріледі; шығыс POST сұраныстары қайта бағыттауларды қадағаламайды. Тіркелгі бес нүктеге дейін тіркей алады.

Растау оқиғасында livemode=false болады. Сәтті HTTP мәртебесі жалғыз өзі жеткіліксіз: шақырту нақты сәйкес келуі керек. Құпияны айналдыру қайта растауды талап етеді.

1. 1

   Саудагер тіркелгіңіздегі /account#webhooks мекенжайында қоғамдық HTTPS URL, сипаттама және сізге қажет оқиға түрлерін енгізіңіз.

2. 2

   Берілген құпияны сервер жағындағы сақтауда сақтаңыз. Оның толық мәні бір рет көрсетіледі.

3. 3

   Қолтаңбаларды бастапқы сұраныс байттары бойынша тексеріңіз.

4. 4

   Нүкте растауын іске қосыңыз. endpoint.verification үшін data.challenge мәнін қайтаратын JSON қайтарыңыз: {"challenge":"the received value"}.

5. 5

   Расталған нүктені қосыңыз және жеткізу тарихын тексеріңіз.

Оқиға конверті#

id оқиғаның әрбір жеткізу әрекетінде бірдей қалады. createdAt — миллисекундтағы Unix уақыт белгісі, ал apiVersion келісімшарт нұсқасын анықтайды. data сақталған сервер нысанын қамтиды; мысал қысқартылған.

livemode=true нақты сервер оқиғасын конечная нүктесін тексеруден ажыратады. Бұл шоттың төленгенін білдірмейді: type және төлем деректерін тексеріңіз. Белгілі оқиға түрлерін өңдеңіз және схеманы растаңыз.

{
  "id": "evt_example",
  "type": "invoice.created",
  "apiVersion": "2026-10-21",
  "createdAt": 1792540800000,
  "livemode": true,
  "data": {
    "invoice": {
      "id": "lnk_example",
      "orderId": "order-1042",
      "currency": "USD",
      "amountMinor": 500,
      "vatCustomerPercent": 100,
      "feeCustomerPercent": 0
    }
  }
}

HMAC-SHA256 растаңыз#

Kevmi-Signature құрамында t=секунд,v1=hex бар. Қолтаңба — уақыт белгісі жолы, нүкте және түпнұсқа дене үстінен HMAC-SHA256: уақыт белгісі + "." + rawBody. Арнайы конечная нүктесі құпиясын және тұрақты уақыт салыстыруын қолданыңыз.

Уақыт белгісі сервер уақытынан 300 секундтан артық екі бағытта айырмашылығы бар қолтаңбаларды қабылдамаңыз. Сағаттарды синхрондаңыз. Растау алдында JSON-ды талдап қайта сериализацияламаңыз: бос орындар мен қасиет тәртібі қол қойылған байттарға әсер етеді.

import { createHmac, timingSafeEqual } from 'node:crypto';

function verifyKevmi(rawBody, header, secret, nowSeconds) {
  const match = /^t=(\d{10}),v1=([a-f0-9]{64})$/.exec(header || '');
  if (!match || Math.abs(nowSeconds - Number(match[1])) > 300) {
    return false;
  }
  const expected = createHmac('sha256', secret)
    .update(match[1] + '.')
    .update(rawBody)
    .digest();
  const received = Buffer.from(match[2], 'hex');
  return expected.length === received.length
    && timingSafeEqual(expected, received);
}

// Read bytes before JSON parsing; cap the request body.
// secret comes from your server secret store.
const valid = verifyKevmi(rawBody, signature, secret,
  Math.floor(Date.now() / 1000));
if (!valid) throw new Error('Invalid webhook signature');
const event = JSON.parse(rawBody.toString('utf8'));
// Validate the event schema and persist its ID together
// with your order update in one database transaction.
// Return a 2xx response after durable acceptance.

Қайта әрекеттер және растау#

Кез келген 2xx жауабы қарапайым оқиғаны растайды. Жауап беру алдында оқиғаны сенімді түрде сақтаңыз; ауыр жұмыс сіздің өз кезегіңіз арқылы жалғасуы мүмкін. Жауап уақыты — сегіз секунд. Желі қатесі немесе 2xx емес жауап қайта әрекетті жоспарлайды.

Ең көбі алты әрекет бар: бастапқы жеткізу плюс бір минут, бес минут, 30 минут, екі сағат және 12 сағат кідірістері қатарынан сәтсіздіктерден кейін. Бұлар кезек кестелері, нақты жеткізу уақытының кепілдігі емес. Әрекеттерді тауысу жеткізуді сәтсіз деп белгілейді.

Жеткізу кемінде бір рет жүзеге асырылады және қатаң реттілікті уәде етпейді. Бірегей оқиға идентификаторын тапсырыс жаңартуыңызбен бір транзакцияда сақтаңыз. Бұрын қолданылған қайталанған жазба тапсырысты қайта орындамай 2xx алуы керек.

Қолмен қайта әрекет жеткізу әрекеттерін қайта бастайды, түпнұсқа оқиға ID, жеткізу ID және нақты денені сақтай отырып. Әрбір әрекет жаңа қолтаңба уақыт белгісін алады. Конечная нүктесін кідірту оның кезегін сақтайды; жою күтіп тұрған және сәтсіз жеткізулерді болдырмайды.

Жеткізу тарихы және келістіру#

Интерфейс конечная нүктесі күйін, жақындағы жеткізулерді, әрекет санын, соңғы HTTP жауабын, қатені және келесі әрекет уақытын көрсетеді. Бұл диагностикалар сіздің өз тапсырыс жазбаларыңызды толықтырады.

GET /api/v1/events events:read арқылы 50-ге дейін оқиғаны және nextCursor қайтарады. Мөлдір емес nextCursor мәнін cursor ретінде өзгеріссіз беріңіз; null соңын белгілейді. Реттеу createdAt және id екеуін де қолданады. Ескі before Unix-миллисекунд шекарасы бөлек қолжетімді және cursor-мен біріктірілмейді. Расталған конечная нүктелері тіркелуінен ерте емес оқиғаларды алады; кідіртілген конечная нүктелері қайта жалғастырудан кейін жеткізу үшін кезектегі оқиғаларды жинауды жалғастырады. Бұл конечная нүктесін құру алдындағы тарихты уәде етпейді.

Кіріс шлюз түбіртегін тексеру#

Gateway v3 /api/gateway/webhook адресіне X-Gateway-Event-Id, X-Gateway-Timestamp және X-Gateway-Signature: v1=<hex> жібереді. HMAC-SHA256 уақыт белгісі + "." + rawBody мәніне GATEWAY_WEBHOOK_SECRET кілтімен қол қояды; сағат терезесі — 300 секунд. Тақырып/дене ID теңдігі, API нұсқасы, тірі режим және дене хэші тексеріледі.

Әртүрлі дене байттарымен қайта қолданылған оқиға ID қабылданбайды. Қол қойылған хабарландыру нақты операцияның аутентификацияланған GET сұрауын іске қосады. Тапсырыс, әдіс, валюта, база, мақұлданған сома және нұсқа тексеріледі. Сәттілік fulfillment_ready=true, verification=provider_confirmed, нақты төленген сома және дау-дамайдың болмауын талап етеді; крипто сондай-ақ расталған есеп айырысу дәлелін қажет етеді.

Кіріс өңдеу, түбіртектер және сатушы оқиғалары қайталанудан қорғалған. Ескі тек шолғыштағы хабарландыру форматтары сәтті төлемді белгілей алмайды. Сатушы вебхуктері ешқашан карта өрістерін, банк кодтарын, QR деректерін, провайдер тіркелгі деректерін немесе шлюз құпиясын қамтымайды.

Telegram жеке келісімшартқа ие#

POST /api/telegram/webhook X-Telegram-Bot-Api-Secret-Token, жаңарту құрылымын және жіберушіні тексереді. update_id қайталап өңдеуден қорғайды. Бұл маршрут кіру, командалар, қолдау және модерация әрекеттерін өңдейді; ол қаржылық түбіртектерді қабылдамайды.

Орналастыру иесі бот токенін, вебхук құпиясын, setWebhook тіркелуін және қолжетімді HTTPS мекенжайын конфигурациялайды. Олар сатушы конечная нүктесі қолтаңба құпиясынан бөлек.

Бірнеше дүкен және бір АҚШ доллары базалық бағасы#

Жиынтық аналитика мен операциялар үшін Барлық дүкендерді таңдаңыз немесе жеке жазбалары үшін дүкенді таңдаңыз. Әр дүкеннің жеке storeId, атауы, ҚҚС әдепкі мәні, шоттары, API кілттері, вебхук нүктелері, оқиғалар тарихы және веб-сайт қосымшасы бар. Хабарландырулар мен қолдау билеттері тіркелгіге тиесілі. Тіркелгі 100 дүкенге дейін құра алады. Бар жазбалар оның бірінші дүкенінде қалады.

Жаңа жұмыс кеңістігі шоттары pricingMode="universal" және АҚШ доллары базалық бағасын пайдаланады. Any карта, alipay, sbp және криптоны қамтиды; сатушы ішкі жиынтықты таңдай алады. Карталар мен Alipay АҚШ долларымен есептейді. SBP Ресей Банкінің АҚШ доллары/рубль анықтамалық бағамын пайдаланып рубльмен есептейді. Крипто айқын шот ережесі бойынша USDT-мен есептейді: 1 АҚШ доллары = 1 USDT. Бұл шот айырбастау ережесі, нарықтық USDT котировкасы емес. Шлюз таңдалған монетаның бағамын, нақты аударым сомасын және нұсқауларды аударымға дейін береді.

Анықтамалық бағам және екі сома да құру кезінде мұздатылады. Рубльге айырбастауды қамтитын шоттар 24 сағат ішінде мерзімі аяқталады. Егер анықтамалық бағамды алу мүмкін болмаса, құру FX_UNAVAILABLE қатесімен сәтсіз аяқталады; ойдан шығарылған немесе ескірген қосалқы бағам пайдаланылмайды. Меншік иесінің жауабындағы amountMinor және quotes АҚШ доллары бухгалтерлік валютасын пайдаланады. quotes[method].settlement туынды валютадағы төлем котировкасын қамтиды. Қоғамдық төлем беті таңдалған төлем валютасын currency өрісінде, бастапқы бағаны baseAmountMinor/baseCurrency өрістерінде және анықтамалық бағамды fx өрісінде көрсетеді. Төлем жіберілгеннен кейін оның әдісін өзгерту мүмкін емес; шотта бір шлюз операциясы болады.

Мақсатты дүкен ішінде API кілтін жасаңыз және серверіңізден Authorization: Bearer <key> жіберіңіз. Оның дүкенге байланыстыруы өзгермейді; X-Kevmi-Store оған басқа дүкенге қолжетімділік бере алмайды. Браузер сеанстары X-Kevmi-Store: <storeId> таңдайды; оны алып тастағанда бірінші дүкен таңдалады. all мәні тек GET /api/account/dashboard және GET /api/payment-links сұраулары арқылы қабылданады. Өзгертулер таңдалған дүкенді, Origin және X-CSRF-Token талап етеді. Тіркелгі идентификаторлары мен дүкен идентификаторлары әртүрлі идентификаторлар болып табылады.

Үйлесімділік үшін pricingMode="universal" жоқ API сұраулары қолма-қол баға белгілеуді және бастапқы валюта шектеулерін сақтайды. Бар шоттар ешқашан қайта есептелмейді. Аналитикадағы расталған түбіртектер тексерілген төлемдерден сақталған шот шығындарын шегергендегі соманы көрсетеді; олар шығарылатын баланс емес. Мұрагерлік шот валюталары бөлек қалады, ал төлемдер қолдау қызметімен келісіледі. Тапсырысты тек payment.fulfillmentReady=true және payment.status="succeeded" сервер API, оқиғалар тарихы немесе қол қойылған вебхук арқылы тексергеннен кейін орындаңыз.