Қосу тәсілін таңдаңыз
API токенін алыңыз
Кабинет → «Менің сайттарым» → сайтты таңдаңыз → «API кілттері» → «Токен жасау». Құпия бір рет көрсетіледі.
Сайтты қосыңыз
Ресурс — сайттың мекенжайы. Сатып алушыны қайтару мекенжайлары осы мекенжайда болуы керек.
Кассаны таңдаңыз
Ресурс бір Kaspi кассасына байланған; токен ресурсты да, кассаны да анықтайды.
Төлем жасаңыз
POST /api/v1/payments → сатып алушыға checkout_url.
Қашықтағы шот жасаңыз
POST /api/v1/invoices/remote — Kaspi-де сатып алушының нөміріне шот.
Мәртебені алыңыз
GET /api/v1/payments/{id} немесе webhook. Төленді — тек status = paid.
Webhooks-ты тексеріңіз
Bankemes-Signature тақырыбындағы HMAC-SHA256 қолтаңбасы.
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"}'POST /api/v1/payments
const res = await fetch('https://bankemes.example/api/v1/payments', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.BANKEMES_TOKEN}`, 'Idempotency-Key': 'order-1001-attempt-1', 'Content-Type': 'application/json' },
body: JSON.stringify({
"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"
}),
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);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-ге өтуі бойынша тапсырысты төленген деп санамаңыз.
- Токен жария болуы мүмкін болса, оны кабинетте бірден кері қайтарып алыңыз.
Құжаттама мен құралдар
Merchant API
Әдістер мен схемалардың толық анықтамалығы
Quickstart
Алғашқы тест қосылымы
MCP
ЖИ-агенттерге арналған құралдар мен протокол
SDK · Node / Python / PHP
Сайт жиынтығынан жүктеу: