Мазмұнға өту

API құжаттамасы

Merchant API v1. Bankemes OpenAPI 3.1 спецификациясынан жасалған.

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 төлем беті)

Сұрау денесінің өрістері
ӨрісТүріШектеулер
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

Қашықтағы шот және оның мәртебесі (базадан)

Сұрау денесінің өрістері
ӨрісТүріШектеулер
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

Төлем мәртебелерінің тарихы

Сұрау денесінің өрістері
ӨрісТүріШектеулер
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 арқылы төленген төлем бойынша. Тірі Kaspi-де әзірге өшірулі

Сұрау денесінің өрістері
ӨрісТүріШектеулер
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/код): бір тапсырыс немесе тұрақты, тіркелген немесе сатып алушы енгізетін сома

Сұрау денесінің өрістері
ӨрісТүріШектеулер
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

Сатушының клиенттері: төленген, қарыз, мерзімі өткен шоттар

Сұрау денесі қажет емес.

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

Клиент құру

Сұрау денесі қажет емес.

Жауаптар
  • 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

Клиентке шот қою

Сұрау денесінің өрістері
ӨрісТүріШектеулер
id *path: stringuuid
Жауаптар
  • 200OK
  • 201Создано
  • 400Ошибка
  • 404Ошибка
  • 409Ошибка
GET/api/v1/customer-invoices/{id}payments:read

Клиент шоты

Сұрау денесінің өрістері
ӨрісТүріШектеулер
id *path: stringuuid
Жауаптар
  • 200OK
  • 201Создано
  • 400Ошибка
  • 404Ошибка
  • 409Ошибка
GET/api/v1/schedulespayments:read

Тұрақты шоттар

Сұрау денесі қажет емес.

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

Тұрақты шот кестесі. Автоматты есептен шығару жоқ

Сұрау денесі қажет емес.

Жауаптар
  • 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

Жаппай шоттар

Сұрау денесі қажет емес.

Жауаптар
  • 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С) экспорт: банк растаған төлемдер, қайтарулар, Kaspi операция нөмірлері

Сұрау денесі қажет емес.

Жауаптар
  • 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_ENABLEDKaspi арқылы қайтару әлі қосылмаған: ақшаны 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_REQUIREDIdempotency-Key тақырыбы жоқ немесе қате.
401API_TOKEN_MISSINGAuthorization тақырыбы жоқ.
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'));
  });
}