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

Разработчикам

Подключение сайта к Bankemes за несколько шагов.

Открыть документацию
  1. Получите API-токен

    Кабинет → «Мои сайты» → выберите сайт → «API-ключи» → «Создать токен». Секрет показывается один раз.

  2. Добавьте сайт

    Ресурс — это адрес сайта. Адреса возврата покупателя должны быть на этом адресе.

  3. Выберите кассу

    Ресурс привязан к одной кассе Kaspi; токен определяет и ресурс, и кассу.

  4. Создайте платёж

    POST /api/v1/payments → checkout_url для покупателя.

  5. Создайте удалённый счёт

    POST /api/v1/invoices/remote — счёт на номер покупателя в Kaspi.

  6. Получите статус

    GET /api/v1/payments/{id} или webhook. Оплачено — только status = paid.

  7. Проверяйте webhooks

    Подпись HMAC-SHA256 в заголовке Bankemes-Signature.

  8. Используйте Idempotency-Key

    Повтор запроса с тем же ключом вернёт тот же объект.

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

Безопасность интеграции

  • Храните токен только на сервере, не в браузере и не в приложении.
  • Проверяйте подпись и время каждого webhook, дедуплицируйте события по id.
  • Не считайте заказ оплаченным по переходу покупателя на success_url.
  • Отзовите токен в кабинете сразу, если он мог утечь.