Выберите способ подключения
Подключить Merchant API
Создать платёж на сервере, принять webhook и проверить итоговый статус.
Открыть QuickstartНастроить через MCP
Выдать ИИ-агенту ограниченный доступ и пройти пошаговую настройку.
Инструкция для ИИ-агентовПодписки и удалённые счета
Создать счёт по номеру телефона и проверять его через API.
Сценарий счетовПолучите API-токен
Кабинет → «Мои сайты» → выберите сайт → «API-ключи» → «Создать токен». Секрет показывается один раз.
Добавьте сайт
Ресурс — это адрес сайта. Адреса возврата покупателя должны быть на этом адресе.
Выберите кассу
Ресурс привязан к одной кассе Kaspi; токен определяет и ресурс, и кассу.
Создайте платёж
POST /api/v1/payments → checkout_url для покупателя.
Создайте удалённый счёт
POST /api/v1/invoices/remote — счёт на номер покупателя в Kaspi.
Получите статус
GET /api/v1/payments/{id} или webhook. Оплачено — только status = paid.
Проверяйте webhooks
Подпись HMAC-SHA256 в заголовке Bankemes-Signature.
Используйте Idempotency-Key
Повтор запроса с тем же ключом вернёт тот же объект.
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"}'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}`);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
Скачать из комплекта сайта: