Skip to content

Bankemes webhooks: signatures, retries and payment confirmation

Verify Bankemes-Signature on the raw body, persist events without duplicates, and verify the amount, order and payment mode before fulfillment.

Bankemes team · Updated

Verify the original body and signature time

A webhook tells your server that a payment changed. It works when the buyer closes the page or never returns to success_url. Bankemes-Signature uses t=<Unix seconds>,v1=<hex>. The signed value is HMAC-SHA256 of the string “t.raw body”, using your resource’s separate webhook secret. A Merchant API token is not that signing secret.

Download the Node.js SDK from the site; this example needs no npm package for Bankemes. constructWebhookEvent checks the signature, rejects clock differences over 300 seconds in either direction, then parses JSON. Synchronize your server clock. Parsing and reserializing JSON, or changing whitespace before verification, breaks the signature. During rotation, any matching v1 is sufficient. The signature timestamp describes delivery; an event’s older created_at does not make a legitimate retry invalid.

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.
}

Persist the event before returning 2xx

Here inbox is your durable storage, not an SDK method. Implement insertIfAbsent with a unique index on event.id; a duplicate of an already saved event is successful. Once persisted, acknowledge with 2xx and process it in your worker. Return an error when persistence fails: a premature 200 can lose the notification. Your worker also needs its own retry mechanism for an event that was saved but not processed.

Deliveries can repeat and arrive out of order. By default Bankemes makes up to 15 attempts within 24 hours, with a 10-second receiver timeout. Do not use HTTP arrival order as order history or substitute Bankemes-Delivery-Id for the unique event.id. A retry must never ship an order or add a paid subscription period twice.

Re-read the payment before fulfillment

For payment.paid or remote_invoice.paid, locate the order by its stored payment_id, rather than user-supplied request data. The event confirms verification through data.bank_verified=true. A payment GET returns status and the detailed state; it has no bank_verified field. Re-read the matching object with your server token, then compare id, order_id, currency, amount_tiyn and livemode against your database. The amount_tiyn string supports exact comparisons without rounding.

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;
}

In one transaction, mark the event processed, record the order payment, and enqueue fulfillment in your durable queue. Enforce uniqueness for the order as well: distinct events must not fulfill it twice. livemode=false belongs to the test environment and does not prove real funds were received. A thank-you page, screenshot or chat message is not payment confirmation.

Before launch

  • Reject a wrong secret, modified body and stale timestamp.
  • Two copies of one event.id fulfill once; a database failure does not receive a false 200.
  • Test paid never fulfills a production order; an amount mismatch goes to review.
  • Process late paid after unverified expiry as confirmed payment.

Exact fields: Merchant API. Uncertain outcomes: payment statuses. End-to-end testing: agent testing guide.

Questions about this topic

Can I verify the signature after JSON.parse?
Keep the original body. Reserializing the object can change the signed bytes; use raw body and constructWebhookEvent before ordinary JSON middleware.
Why deduplicate if there is a 300-second tolerance?
The time window does not prevent duplicates within it or legitimate redelivery with a fresh signature. Unique event.id storage and one-time fulfillment are separate protections.
What if status retrieval temporarily fails?
Persist the event and retry processing in your worker. A network error proves neither payment nor non-payment.
Must I wait for fulfillment before returning 200?
Durable event storage with guaranteed subsequent processing is sufficient. Put slow fulfillment in your queue; persistence failures must return an HTTP error.

Next step