Choose how to connect
Connect the Merchant API
Create a payment on the server, receive a webhook, and verify the final status.
Open QuickstartSet up through MCP
Give an AI agent limited access and follow the step-by-step setup.
Guide for AI agentsSubscriptions and remote invoices
Create an invoice for a phone number and check it through the API.
Invoice workflowGet an API token
Dashboard, My websites, select the website, API keys, Create token. The secret is shown once.
Add the website
A resource is the website address. Buyer return URLs must use that address.
Choose a cashier
A resource is bound to one Kaspi cashier; the token identifies both the resource and cashier.
Create a payment
POST /api/v1/payments returns checkout_url for the buyer.
Create a remote invoice
POST /api/v1/invoices/remote creates an invoice for the buyer’s phone number in Kaspi.
Get the status
Use GET /api/v1/payments/{id} or a webhook. Paid means only status = paid.
Verify webhooks
Verify the HMAC-SHA256 signature in the Bankemes-Signature header.
Use Idempotency-Key
Repeating a request with the same key returns the same object.
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'));
});
}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.
Documentation and tools
Merchant API
Full reference of methods and schemas
Quickstart
Your first test connection
MCP
Tools and protocol for AI agents
SDK · Node / Python / PHP
Download from the site bundle: