Мазмұнға өту

Bankemes webhooks: қолтаңба, қайталау және төлемді растау

Бастапқы сұрау денесінен Bankemes-Signature тексеру, оқиғаны қайталамай сақтау және тауар берер алдында соманы, тапсырысты, төлем режимін растау.

Bankemes командасы · Жаңартылды

Бастапқы дене мен қолтаңба уақытын тексеріңіз

Webhook төлемнің өзгергенін серверіңізге хабарлайды. Сатып алушы бетті жапса немесе success_url арқылы қайтпаса да, ол қажет. Bankemes-Signature пішімі: t=<Unix seconds>,v1=<hex>. Тексерілетін мән — «t.бастапқы дене» жолының HMAC-SHA256 хэші; кілті — ресурстың бөлек webhook құпиясы. Merchant API токені бұл кілтті алмастырмайды.

Node.js SDK-ны сайттан алыңыз; мысалға npm пакеті қажет емес. constructWebhookEvent қолтаңбаны тексеріп, уақыттың екі бағытта да 300 секундтан артық ауытқуын қабылдамайды, содан кейін JSON-ды талдайды. Сервер сағатын синхрондаңыз. Тексеруге дейін JSON талдау, бос орындарды өзгерту немесе қайта сериализациялау қолтаңбаны бұзады. Кілт ауысқанда бірнеше v1 болуы мүмкін: бір сәйкестік жеткілікті. Қолтаңбадағы жеткізу уақыты мен оқиғаның created_at өрісі бөлек: ескі оқиға қайта жеткізілуі мүмкін.

Shell
curl -fsS https://bankemes.kz/sdk/bankemes-node.mjs -o bankemes.mjs
Node.js / Express
import express from 'express';
import { constructWebhookEvent } from './bankemes.mjs';

// inbox.insertIfAbsent must durably save the event with a UNIQUE event.id.
export function registerBankemesWebhook(app, inbox) {
  app.post('/webhooks/bankemes',
    express.raw({ type: 'application/json', limit: '64kb' }),
    async (req, res) => {
      let event;
      try {
        event = constructWebhookEvent(
          req.body,
          req.get('Bankemes-Signature'),
          process.env.BANKEMES_WEBHOOK_SECRET,
        );
      } catch {
        return res.sendStatus(400);
      }
      try {
        await inbox.insertIfAbsent(event.id, event);
        return res.sendStatus(200);
      } catch {
        return res.sendStatus(503);
      }
    });
  // Register express.json() for other routes AFTER this raw-body route.
}

Алдымен оқиғаны сақтап, содан кейін 2xx қайтарыңыз

Мысалдағы inbox — SDK әдісі емес, өзіңіздің тұрақты сақтау орныңыз. insertIfAbsent үшін event.id бойынша бірегей индекс жасаңыз: бұрын сақталған оқиғаның қайталануы сәтті нәтиже саналады. Жазғаннан кейін 2xx қайтарып, өңдеуді өз воркеріңізге беруге болады. Сақтау орны істемесе, қате қайтарыңыз; жазуға дейінгі 200 хабарламаның жоғалуына әкелуі мүмкін. Воркер тоқтап қалса, сақталған оқиғаны қайта өңдеу механизмін де жасаңыз.

Жеткізу қайталануы және ретсіз келуі мүмкін. Әдепкіде Bankemes 24 сағат ішінде 15 ретке дейін әрекет жасайды; қабылдаушыға берілетін уақыт — 10 секунд. HTTP сұрауларының ретін тапсырыс тарихы деп қабылдамаңыз және Bankemes-Delivery-Id мәнін бірегей event.id орнына қолданбаңыз. Қайталау тауарды екінші рет бермеуі немесе төленген кезеңді қайта қоспауы керек.

Тауар берер алдында төлемді қайта оқыңыз

payment.paid немесе remote_invoice.paid келгенде тапсырысты пайдаланушы жіберген деректен емес, сақталған payment_id арқылы табыңыз. Оқиғадағы растау — data.bank_verified=true. GET жауабында status және толық state бар, бірақ bank_verified өрісі жоқ. Нысанды өз сервер токеніңізбен қайта оқып, id, order_id, currency, amount_tiyn және livemode мәндерін БД-мен салыстырыңыз. Жол түріндегі amount_tiyn соманы дөңгелектемей тексеруге мүмкіндік береді.

Node.js
import { Bankemes } from './bankemes.mjs';
const bankemes = new Bankemes({ token: process.env.BANKEMES_API_TOKEN });

// expected comes from YOUR order database, never from the webhook or browser.
export async function verifiedPaidPayment(event, expected) {
  if (!['payment.paid', 'remote_invoice.paid'].includes(event.type)) return null;
  if (event.data.bank_verified !== true) return null;
  const api = event.type === 'remote_invoice.paid'
    ? bankemes.remoteInvoices : bankemes.payments;
  const payment = await api.retrieve(event.data.payment_id);
  if (payment.id !== expected.paymentId
    || payment.order_id !== expected.orderId
    || payment.amount_tiyn !== String(expected.amountTiyn)
    || payment.currency !== 'KZT'
    || payment.livemode !== expected.livemode
    || event.data.livemode !== expected.livemode
    || payment.status !== 'paid' || payment.state !== 'paid') return null;
  return payment;
}

Воркер бір транзакцияда оқиғаны өңделді деп белгілеп, тапсырыс төлемін сақтап, тауар беруді сенімді кезекке қоюы керек. Тапсырыс бойынша да бірегейлік енгізіңіз: әртүрлі оқиға бір тапсырысты екі рет орындамауы тиіс. livemode=false тест ортасына арналған, ол нақты ақшаның түскенін растамайды. «Рақмет» бетіне өту, скриншот немесе чаттағы хабарлама төлем дәлелі емес.

Іске қосар алдында не тексеру керек

  • Қате secret, өзгертілген дене және ескі timestamp қабылданбайды.
  • Бір event.id екі рет келсе де, тауар бір рет беріледі; БД қатесі жалған 200 алмайды.
  • Тест paid өндірісте тауар бермейді; қате сома тексеруге жіберіледі.
  • Расталмаған expired күйінен кейін келген paid расталған төлем ретінде өңделеді.

Нақты өрістер: Merchant API. Белгісіз нәтиже: төлем күйлері. Интеграцияны толық тексеру: агент нұсқаулығы.

Тақырып бойынша сұрақтар

Қолтаңбаны JSON.parse кейін тексеруге бола ма?
Бастапқы денені сақтау қажет. Нысанды қайта сериализациялау қолтаңбаланған байттарды өзгертуі мүмкін; raw body мен constructWebhookEvent әдісін кәдімгі JSON middleware-ден бұрын қолданыңыз.
300 секунд шектеуі болса, қайталауды неге тексеру керек?
Рұқсат етілген уақыт терезе ішіндегі қайталауды не жаңа қолтаңбамен қайта жеткізуді тоқтатпайды. Бірегей event.id және тауарды бір рет беру бөлек қажет.
GET мәртебе сұрауы уақытша істемесе не істеу керек?
Оқиғаны сақтап, өз воркеріңізбен өңдеуді қайталаңыз. Желі қатесіне қарап тапсырысты төленді немесе төленбеді деп белгілемеңіз.
200 жауабын тауар жіберілген соң ғана қайтару керек пе?
Оқиғаны сенімді сақтап, кейін өңделуін қамтамасыз ету жеткілікті. Баяу беруді өз кезегіңізге шығарыңыз; жазу қатесі HTTP қатесін қайтаруы керек.

Келесі қадам