Skip to content

Developers

Connect a website to Bankemes in a few steps.

Open documentation
  1. Get an API token

    Dashboard, My websites, select the website, API keys, Create token. The secret is shown once.

  2. Add the website

    A resource is the website address. Buyer return URLs must use that address.

  3. Choose a cashier

    A resource is bound to one Kaspi cashier; the token identifies both the resource and cashier.

  4. Create a payment

    POST /api/v1/payments returns checkout_url for the buyer.

  5. Create a remote invoice

    POST /api/v1/invoices/remote creates an invoice for the buyer’s phone number in Kaspi.

  6. Get the status

    Use GET /api/v1/payments/{id} or a webhook. Paid means only status = paid.

  7. Verify webhooks

    Verify the HMAC-SHA256 signature in the Bankemes-Signature header.

  8. Use Idempotency-Key

    Repeating a request with the same key returns the same object.

POST /api/v1/payments
curl -X POST "https://bankemes.example/api/v1/payments" \
  -H "Authorization: Bearer bms_live_XXXXXXXX_your-secret-token" \
  -H "Idempotency-Key: order-1001-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"ORDER-1001","amount":1500,"currency":"KZT","description":"Заказ №1001","success_url":"https://shop.example.kz/orders/1001/thanks","cancel_url":"https://shop.example.kz/cart"}'
Bankemes-Signature
import crypto from 'node:crypto';

export function verifyBankemesWebhook(secret, header, rawBody, toleranceSec = 300) {
  const parts = Object.groupBy(header.split(','), (p) => p.split('=')[0]);
  const t = Number(parts.t?.[0]?.split('=')[1]);
  if (!Number.isFinite(t) || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return (parts.v1 ?? []).some((p) => {
    const got = Buffer.from(p.split('=')[1] ?? '', 'hex');
    return got.length === 32 && crypto.timingSafeEqual(got, Buffer.from(expected, 'hex'));
  });
}

Integration security

  • Keep the token on the server, never in the browser or application.
  • Verify the signature and timestamp of every webhook, and deduplicate events by id.
  • Do not mark an order paid when a buyer opens success_url.
  • Revoke a token in the dashboard immediately if it may have leaked.