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

Документация API

Merchant API v1. Сформировано из спецификации OpenAPI 3.1 Bankemes.

OpenAPI 1.2.0 · Источник: docs/api/openapi.yaml

Авторизация

API-токен ресурса; только заголовок Authorization

HTTP
Authorization: Bearer bms_live_XXXXXXXX_your-secret-token

Idempotency-Key

Повтор запроса с тем же ключом вернёт тот же объект. Кабинет предупредит вас, новые платежи через эту кассу приостановятся до переподключения. Проверка уже созданных платежей продолжится после переподключения.

HTTP
Idempotency-Key: order-1001-attempt-1

Методы

POST/api/v1/paymentspayments:createIdempotency-Key

Создать платёж (страница оплаты Bankemes, Kaspi QR)

Поля тела запроса
ПолеТипОграничения
order_id *stringpattern ^[A-Za-z0-9_.:#/-]{1,64}$
amount *integerЦелое число тенге (JSON-число). Дроби, строки и экспоненциальная запись отклоняются (INVALID_AMOUNT); ≥ 1; ≤ 100000000
currency"KZT"
descriptionstring≤ 200 символов
success_urlstringR5: только origin ресурса (иначе 400, fields.success_url = origin_mismatch); pattern ^https://; uri
cancel_urlstringR5: только origin ресурса; pattern ^https://; uri
expires_ininteger≥ 300; ≤ 86400; по умолчанию 1800
metadataobjectВаши данные (ключи: латиница, цифры, _ . -). Возвращаются в API и webhook, в банк не передаются. До 2 КБ
itemsobject[]Состав заказа (показывается на странице оплаты); сумма quantity × price = amount
cURL
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"}'
Ответы
  • 200Повтор с тем же Idempotency-Key: та же операция в текущем состоянии; заголовок Idempotent-Replayed: true
  • 201Создан
  • 400Ошибка
  • 401Ошибка
  • 402Ошибка
  • 403Ошибка
  • 409Ошибка
  • 429Ошибка
GET/api/v1/paymentspayments:read

Платежи ресурса токена (новые сверху)

Поля тела запроса
ПолеТипОграничения
limitquery: integer≥ 1; ≤ 100; по умолчанию 20
order_idquery: stringpattern ^[A-Za-z0-9_.:#/-]{1,64}$
starting_afterquery: stringid последнего полученного объекта; uuid
cURL
curl -X GET "https://bankemes.example/api/v1/payments?limit=20&order_id=ORDER-1001" \
  -H "Authorization: Bearer bms_live_XXXXXXXX_your-secret-token"
Ответы
  • 200Список
  • 401Ошибка
  • 403Ошибка
GET/api/v1/payments/{id}payments:read

Платёж (только из базы Bankemes; чужой ресурс — 404)

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
cURL
curl -X GET "https://bankemes.example/api/v1/payments/{id}" \
  -H "Authorization: Bearer bms_live_XXXXXXXX_your-secret-token"
Ответы
  • 200OK
  • 404Ошибка
POST/api/v1/invoices/remoteremote-invoices:createIdempotency-Key

Выставить удалённый счёт Kaspi Pay на номер покупателя

Поля тела запроса
ПолеТипОграничения
order_id *stringpattern ^[A-Za-z0-9_.:#/-]{1,64}$
phone *stringмобильный номер Казахстана покупателя
amount *integerЦелое число тенге (JSON-число). Дроби, строки и экспоненциальная запись отклоняются (INVALID_AMOUNT); ≥ 1; ≤ 100000000
currency"KZT"
descriptionstringвидно покупателю в Kaspi; к нему добавляется « · BMS-XXXXXXXXXX»; ≤ 200 символов
expires_ininteger≥ 300; ≤ 86400; по умолчанию 1800
cURL
curl -X POST "https://bankemes.example/api/v1/invoices/remote" \
  -H "Authorization: Bearer bms_live_XXXXXXXX_your-secret-token" \
  -H "Idempotency-Key: remote-1001-attempt-1" \
  -H "Content-Type: application/json" \
  -d '{"order_id":"REMOTE-1001","phone":"+77001234567","amount":2500,"currency":"KZT","description":"Счёт по заказу №1001"}'
Ответы
  • 200Повтор с тем же Idempotency-Key: та же операция в текущем состоянии; заголовок Idempotent-Replayed: true
  • 201Выставлен в Kaspi
  • 202Результат создания неизвестен (creation_unknown) или ещё создаётся
  • 400Ошибка
  • 401Ошибка
  • 402Ошибка
  • 403Ошибка
  • 409Ошибка
  • 422Ошибка
  • 429Ошибка
  • 503Ошибка
GET/api/v1/invoices/remoteremote-invoices:read

Удалённые счета ресурса токена

Поля тела запроса
ПолеТипОграничения
limitquery: integer≥ 1; ≤ 100; по умолчанию 20
order_idquery: stringpattern ^[A-Za-z0-9_.:#/-]{1,64}$
starting_afterquery: stringid последнего полученного объекта; uuid
Ответы
  • 200Список
GET/api/v1/invoices/remote/{id}remote-invoices:read

Удалённый счёт и его статус (из базы; сверку с Kaspi делает сервер)

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
Ответы
  • 200OK
  • 404Ошибка
POST/api/v1/invoices/remote/{id}/cancelremote-invoices:create

Отменить неоплаченный удалённый счёт (cancelled — только после подтверждения Kaspi)

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
cURL
curl -X POST "https://bankemes.example/api/v1/invoices/remote/{id}/cancel" \
  -H "Authorization: Bearer bms_live_XXXXXXXX_your-secret-token"
Ответы
  • 200Текущее состояние после отмены (paid остаётся paid)
  • 404Ошибка
  • 409Ошибка
  • 422Ошибка
  • 503Ошибка
POST/api/v1/payments/{id}/cancelpayments:create

Отменить платёж Checkout: без открытой попытки в банке — сразу; иначе решает банк (оплаченный остаётся оплаченным), новых попыток нет

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
Ответы
  • 200Платёж
  • 404Ошибка
  • 409Ошибка
GET/api/v1/payments/{id}/eventspayments:read

История статусов платежа (type, from_status, to_status, at)

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
Ответы
  • 200Список
  • 404Ошибка
GET/api/v1/invoices/remote/{id}/eventsremote-invoices:read

История статусов удалённого счёта

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
Ответы
  • 200Список
  • 404Ошибка
POST/api/v1/payments/{id}/refundspayments:createIdempotency-Key

Возврат (полный или частичный) оплаченного через Kaspi QR платежа. Idempotency-Key обязателен. 201 succeeded, 422 failed, 202 unknown (не повторяется, блокирует следующие возвраты до проверки). Для живого Kaspi выключен (503 REFUNDS_NOT_ENABLED), пока контракт не проверен

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
amountintegerЦелое число тенге (JSON-число). Дроби, строки и экспоненциальная запись отклоняются (INVALID_AMOUNT); ≥ 1; ≤ 100000000
reasonstring≤ 200 символов
Ответы
  • 200Повтор с тем же Idempotency-Key: та же операция в текущем состоянии; заголовок Idempotent-Replayed: true
  • 201Возврат принят Kaspi
  • 202Результат неизвестен
  • 409Ошибка
  • 422Kaspi отклонил
  • 503Ошибка
GET/api/v1/payments/{id}/refundspayments:read

Возвраты платежа и возвращённая сумма

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
Ответы
  • 200Список
  • 404Ошибка
POST/api/v1/payment-linkspayments:createIdempotency-Key

Ссылка на оплату (/l/код): один заказ или многоразовая, фиксированная сумма или сумму вводит покупатель (min/max), срок, лимит оплат. Каждый плательщик многоразовой ссылки получает новый платёж

Поля тела запроса
ПолеТипОграничения
title *string≤ 120 символов
descriptionstring≤ 200 символов
amount_mode"fixed" | "open"
amountintegerЦелое число тенге (JSON-число). Дроби, строки и экспоненциальная запись отклоняются (INVALID_AMOUNT); ≥ 1; ≤ 100000000
min_amountintegerЦелое число тенге (JSON-число). Дроби, строки и экспоненциальная запись отклоняются (INVALID_AMOUNT); ≥ 1; ≤ 100000000
max_amountintegerЦелое число тенге (JSON-число). Дроби, строки и экспоненциальная запись отклоняются (INVALID_AMOUNT); ≥ 1; ≤ 100000000
reusablebooleanпо умолчанию false
max_paymentsinteger≥ 1
expires_atstringdate-time
success_urlstringuri
metadataobjectВаши данные (ключи: латиница, цифры, _ . -). Возвращаются в API и webhook, в банк не передаются. До 2 КБ
Ответы
  • 201Ссылка
  • 400Ошибка
POST/api/v1/payment-links/{id}/revokepayments:createIdempotency-Key

Отключить ссылку (начатые платежи завершаются как обычно)

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
Ответы
  • 200Ссылка
  • 404Ошибка
GET/api/v1/customerspayments:read

Клиенты продавца (поиск q, tag, overdue=1) со сводкой: оплачено, долг, просроченные счета. Только live-токен

Тело запроса не нужно.

Ответы
  • 200OK
  • 201Создано
  • 400Ошибка
  • 404Ошибка
  • 409Ошибка
POST/api/v1/customerspayments:createIdempotency-Key

Клиент: name, phone (для счёта в Kaspi; хранится зашифрованным), email, tags, external_id, channels (порядок каналов уведомлений)

Тело запроса не нужно.

Ответы
  • 200OK
  • 201Создано
  • 400Ошибка
  • 404Ошибка
  • 409Ошибка
GET/api/v1/customers/{id}payments:read

Клиент, его счета (состояние по подтверждённому банком платежу) и расписания

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
Ответы
  • 200OK
  • 201Создано
  • 400Ошибка
  • 404Ошибка
  • 409Ошибка
PATCH/api/v1/customers/{id}payments:create

Изменить клиента

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
Ответы
  • 200OK
  • 201Создано
  • 400Ошибка
  • 404Ошибка
  • 409Ошибка
POST/api/v1/customers/{id}/invoicespayments:createIdempotency-Key

Выставить счёт клиенту сейчас: method remote_invoice (счёт в Kaspi на телефон) или payment_link; amount/description или template_id; due_days

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
Ответы
  • 200OK
  • 201Создано
  • 400Ошибка
  • 404Ошибка
  • 409Ошибка
GET/api/v1/customer-invoices/{id}payments:read

Счёт клиента: issue_state (выпуск) и state (open, paid, expired, cancelled, failed) по платежу

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
Ответы
  • 200OK
  • 201Создано
  • 400Ошибка
  • 404Ошибка
  • 409Ошибка
GET/api/v1/schedulespayments:read

Регулярные счета (customer_id — фильтр)

Тело запроса не нужно.

Ответы
  • 200OK
  • 201Создано
  • 400Ошибка
  • 404Ошибка
  • 409Ошибка
POST/api/v1/schedulespayments:createIdempotency-Key

Регулярный счёт: cadence daily | weekly (weekday 1–7) | monthly (month_day 1–28 или last) | custom (custom_dates), every_n, local_hour (Алматы), start_date, end_date, missed_policy latest | all, reminder_hours, due_days. Каждый период — один обычный счёт; автосписания нет

Тело запроса не нужно.

Ответы
  • 200OK
  • 201Создано
  • 400Ошибка
  • 404Ошибка
  • 409Ошибка
GET/api/v1/schedules/{id}payments:read

Расписание и его счета по периодам

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
Ответы
  • 200OK
  • 201Создано
  • 400Ошибка
  • 404Ошибка
  • 409Ошибка
POST/api/v1/schedules/{id}/pausepayments:createIdempotency-Key

Приостановить расписание

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
Ответы
  • 200OK
  • 201Создано
  • 400Ошибка
  • 404Ошибка
  • 409Ошибка
POST/api/v1/schedules/{id}/resumepayments:createIdempotency-Key

Возобновить (пропущенные за паузу периоды не выставляются)

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
Ответы
  • 200OK
  • 201Создано
  • 400Ошибка
  • 404Ошибка
  • 409Ошибка
POST/api/v1/schedules/{id}/cancelpayments:create

Отменить расписание

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
Ответы
  • 200OK
  • 201Создано
  • 400Ошибка
  • 404Ошибка
  • 409Ошибка
POST/api/v1/bulk-invoicespayments:createIdempotency-Key

Массовые счета: rows [{customer_id | name+phone, amount, description, order_id}] или csv; method; due_days. Некорректные строки — в rejected_rows. Выпуск идёт фоном с ограничением скорости

Тело запроса не нужно.

Ответы
  • 200OK
  • 201Создано
  • 400Ошибка
  • 404Ошибка
  • 409Ошибка
GET/api/v1/bulk-invoices/{id}payments:read

Пакет счетов: статус, счётчики по состояниям, строки

Поля тела запроса
ПолеТипОграничения
id *path: stringuuid
Ответы
  • 200OK
  • 201Создано
  • 400Ошибка
  • 404Ошибка
  • 409Ошибка
GET/api/v1/reports/paymentspayments:read

Выгрузка для бухгалтерии (1С): подтверждённые банком платежи ресурса за период (from, to — даты Алматы), возвраты, номер операции Kaspi, metadata; format=csv — CSV для Excel/1С. fiscal_receipt всегда пуст: фискальный провайдер не подключён. Только live-токен

Тело запроса не нужно.

Ответы
  • 200OK
  • 400Ошибка
GET/api/v1/reports/reconciliationpayments:read

Сверка по дням и кассам: оплачено, возвращено, нетто; открытые и требующие проверки платежи

Тело запроса не нужно.

Ответы
  • 200OK
  • 400Ошибка

Коды ошибок

JSON
{ "error": { "code": "VALIDATION_FAILED", "message": "…", "request_id": "…", "fields": { "amount": "invalid" } } }
Коды ошибок
HTTPcode
410LINK_INACTIVEСсылка на оплату отключена, истекла, уже оплачена или исчерпала лимит (error.reason).
503REFUNDS_NOT_ENABLEDВозвраты через Kaspi ещё не включены: верните деньги в приложении Kaspi Pay.
409REFUND_NOT_ALLOWEDВернуть можно только оплаченный через Kaspi QR платёж.
409REFUND_AMOUNT_EXCEEDEDСумма возврата больше остатка (error.refundable_amount).
409REFUND_UNRESOLVEDПо платежу есть возврат с неизвестным результатом — проверьте его в Kaspi Pay.
400CONFIRMATION_REQUIREDНужно явное подтверждение финансовой операции.
409SCHEDULE_STATEДействие недоступно в текущем статусе расписания.
400IMPORT_INVALIDФайл или список строк не подходит (подробности по строкам в ответе).
409CHANNEL_NOT_CONFIGUREDКанал уведомлений не подключён.
400VALIDATION_FAILEDНеверное поле запроса (подробности в error.fields).
400INVALID_AMOUNTСумма — целое число тенге от 1 до 100 000 000.
400INVALID_PHONEНеверный номер покупателя.
400IDEMPOTENCY_KEY_REQUIREDНет или неверный заголовок Idempotency-Key.
401API_TOKEN_MISSINGНет заголовка Authorization.
401API_TOKEN_INVALIDНеверный токен (или токен передан в адресе).
401API_TOKEN_REVOKEDТокен отозван.
401API_TOKEN_EXPIREDСрок токена истёк.
402SUBSCRIPTION_INACTIVEПодписка кассы не активна: новые платежи недоступны.
403API_TOKEN_SCOPEУ токена нет нужного разрешения.
403ACCOUNT_INACTIVEАккаунт продавца приостановлен.
404NOT_FOUNDНет такой операции у ресурса токена.
409ORDER_ALREADY_EXISTSЗаказ уже создан с другим ключом (error.payment_id).
409IDEMPOTENCY_KEY_REUSEDТот же ключ с другими данными.
409CASHIER_NOT_CONNECTEDКасса не подключена к Kaspi.
409PAYMENT_STATEДействие недоступно в текущем статусе.
422PROVIDER_REJECTEDБанк отказал, операция не создана.
429RATE_LIMITEDЛимит частоты (заголовок Retry-After).
503GATEWAY_UNAVAILABLEВременно: повторите с тем же Idempotency-Key.

Webhooks

payment.createdpayment.paidpayment.failedpayment.expiredpayment.cancelledpayment.needs_reviewremote_invoice.createdremote_invoice.paidremote_invoice.cancelled
Пример события
{
  "id": "evt_AbCdEfGhIjKlMnOpQrStUvWx",
  "type": "payment.paid",
  "created_at": "2026-10-21T10:15:00.000Z",
  "data": {
    "payment_id": "6f1c…",
    "object": "payment",
    "order_id": "ORDER-1001",
    "amount": 1500,
    "amount_tiyn": "150000",
    "currency": "KZT",
    "status": "paid",
    "state": "paid",
    "bank_verified": true,
    "status_reason": "bank_confirmed",
    "paid_at": "2026-10-21T10:14:58.000Z",
    "provider": "kaspi",
    "payment_method": "kaspi_qr",
    "provider_operation_id": "…",
    "resource_id": "…"
  }
}
Проверка подписи (Node.js)
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'));
  });
}