Проверяйте исходное тело и время подписи
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 события решают разные задачи: старое событие может законно прийти повторно.
curl -fsS https://bankemes.kz/sdk/bankemes-node.mjs -o bankemes.mjsimport 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 позволяет сравнить точную сумму без округления.
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.