Перейти к содержимому

Webhooks Bankemes: подпись, повторы и подтверждение оплаты

Как проверить Bankemes-Signature на исходном теле, сохранить событие без дублей и подтвердить сумму, заказ и режим платежа перед выдачей товара.

Команда Bankemes · Обновлено

Проверяйте исходное тело и время подписи

Webhook сообщает вашему серверу об изменении платежа. Он нужен, даже если покупатель закрыл страницу или не вернулся по success_url. Подпись Bankemes-Signature имеет формат t=<Unix seconds>,v1=<hex>. Проверяемое значение — HMAC-SHA256 от строки «t.исходное тело», ключ — отдельный webhook secret вашего ресурса. Merchant API token для этого не подходит.

Получите 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 делает до 15 попыток в пределах 24 часов; таймаут приёмника — 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 не выдаёт товар в продакшене; неправильная сумма уходит на разбор.
  • Поздний paid после неподтверждённого expired обрабатывается как подтверждённая оплата.

Точные поля: Merchant API. Разбор неопределённого результата: статусы платежей. Полный тест интеграции: руководство для агента.

Вопросы по теме

Можно проверить подпись после JSON.parse?
Нужно сохранить исходное тело. Повторная сериализация объекта может изменить подписанные байты; используйте raw body и constructWebhookEvent до обычного JSON middleware.
Зачем дедупликация, если есть ограничение 300 секунд?
Допустимое время не запрещает повторы внутри окна и легитимную повторную доставку с новой подписью. Уникальный event.id и однократная выдача нужны отдельно.
Что делать, если GET статуса временно не работает?
Сохраните событие и повторите обработку своим воркером. Не отмечайте заказ оплаченным или неоплаченным по сетевой ошибке.
Нужно отвечать 200 только после отправки товара?
Достаточно надёжно сохранить событие и обеспечить дальнейшую обработку. Медленную выдачу вынесите в свою очередь; ошибка записи должна вернуть ошибку HTTP.

Следующий шаг