Мазмұнға өту

Әзірлеушілерге

Сайтты 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-ты тексеріңіз

    Bankemes-Signature тақырыбындағы HMAC-SHA256 қолтаңбасы.

  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-ге өтуі бойынша тапсырысты төленген деп санамаңыз.
  • Токен жария болуы мүмкін болса, оны кабинетте бірден кері қайтарып алыңыз.