Skip to content

API documentation

Merchant API v1. Generated from the Bankemes OpenAPI 3.1 specification.

OpenAPI 1.2.0 · Source: docs/api/openapi.yaml

Authentication

Resource API token; Authorization header only

HTTP
Authorization: Bearer bms_live_XXXXXXXX_your-secret-token

Idempotency-Key

Repeating a request with the same key returns the same object. The dashboard warns you and new payments through that cashier pause until reconnection. Existing payment checks resume after reconnection.

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

Methods

POST/api/v1/paymentspayments:createIdempotency-Key

Create a payment (Bankemes checkout page, Kaspi QR)

Request body fields
FieldTypeConstraints
order_id *stringpattern ^[A-Za-z0-9_.:#/-]{1,64}$
amount *integerA whole number of tenge (JSON number). Fractions, strings, and exponential notation are rejected (INVALID_AMOUNT); ≥ 1; ≤ 100000000
currency"KZT"
descriptionstring≤ 200 characters
success_urlstringR5: the resource origin only (otherwise 400, fields.success_url = origin_mismatch); pattern ^https://; uri
cancel_urlstringR5: the resource origin only; pattern ^https://; uri
expires_ininteger≥ 300; ≤ 86400; default 1800
metadataobjectYour data (keys: Latin letters, digits, _ . -). Returned in the API and webhooks, never sent to the bank. Up to 2 KB
itemsobject[]Order items (shown on the checkout page); the sum of 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"}'
Responses
  • 200Repeat with the same Idempotency-Key: the same operation in its current state; header Idempotent-Replayed: true
  • 201Created
  • 400Error
  • 401Error
  • 402Error
  • 403Error
  • 409Error
  • 429Error
GET/api/v1/paymentspayments:read

Payments of the token’s resource (newest first)

Request body fields
FieldTypeConstraints
limitquery: integer≥ 1; ≤ 100; default 20
order_idquery: stringpattern ^[A-Za-z0-9_.:#/-]{1,64}$
starting_afterquery: stringid of the last object received; 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"
Responses
  • 200List
  • 401Error
  • 403Error
GET/api/v1/payments/{id}payments:read

A payment (from the Bankemes database only; another resource returns 404)

Request body fields
FieldTypeConstraints
id *path: stringuuid
cURL
curl -X GET "https://bankemes.example/api/v1/payments/{id}" \
  -H "Authorization: Bearer bms_live_XXXXXXXX_your-secret-token"
Responses
  • 200OK
  • 404Error
POST/api/v1/invoices/remoteremote-invoices:createIdempotency-Key

Issue a Kaspi Pay remote invoice to the buyer’s phone number

Request body fields
FieldTypeConstraints
order_id *stringpattern ^[A-Za-z0-9_.:#/-]{1,64}$
phone *stringthe buyer’s Kazakhstan mobile number
amount *integerA whole number of tenge (JSON number). Fractions, strings, and exponential notation are rejected (INVALID_AMOUNT); ≥ 1; ≤ 100000000
currency"KZT"
descriptionstringvisible to the buyer in Kaspi; " · BMS-XXXXXXXXXX" is appended; ≤ 200 characters
expires_ininteger≥ 300; ≤ 86400; default 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"}'
Responses
  • 200Repeat with the same Idempotency-Key: the same operation in its current state; header Idempotent-Replayed: true
  • 201Issued in Kaspi
  • 202Creation result unknown (creation_unknown) or still being created
  • 400Error
  • 401Error
  • 402Error
  • 403Error
  • 409Error
  • 422Error
  • 429Error
  • 503Error
GET/api/v1/invoices/remoteremote-invoices:read

Remote invoices of the token’s resource

Request body fields
FieldTypeConstraints
limitquery: integer≥ 1; ≤ 100; default 20
order_idquery: stringpattern ^[A-Za-z0-9_.:#/-]{1,64}$
starting_afterquery: stringid of the last object received; uuid
Responses
  • 200List
GET/api/v1/invoices/remote/{id}remote-invoices:read

A remote invoice and its status (from the database; the server reconciles with Kaspi)

Request body fields
FieldTypeConstraints
id *path: stringuuid
Responses
  • 200OK
  • 404Error
POST/api/v1/invoices/remote/{id}/cancelremote-invoices:create

Cancel an unpaid remote invoice (cancelled only after Kaspi confirms)

Request body fields
FieldTypeConstraints
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"
Responses
  • 200Current state after cancellation (paid stays paid)
  • 404Error
  • 409Error
  • 422Error
  • 503Error
POST/api/v1/payments/{id}/cancelpayments:create

Cancel a Checkout payment: immediately if no bank attempt is open; otherwise the bank decides (a paid payment stays paid), and no new attempts are allowed

Request body fields
FieldTypeConstraints
id *path: stringuuid
Responses
  • 200Payment
  • 404Error
  • 409Error
GET/api/v1/payments/{id}/eventspayments:read

Payment status history (type, from_status, to_status, at)

Request body fields
FieldTypeConstraints
id *path: stringuuid
Responses
  • 200List
  • 404Error
GET/api/v1/invoices/remote/{id}/eventsremote-invoices:read

Remote invoice status history

Request body fields
FieldTypeConstraints
id *path: stringuuid
Responses
  • 200List
  • 404Error
POST/api/v1/payments/{id}/refundspayments:createIdempotency-Key

Refund (full or partial) of a payment made through Kaspi QR. Idempotency-Key is required. 201 succeeded, 422 failed, 202 unknown (not retried; blocks further refunds until checked). Disabled for live Kaspi (503 REFUNDS_NOT_ENABLED) until the contract is verified

Request body fields
FieldTypeConstraints
id *path: stringuuid
amountintegerA whole number of tenge (JSON number). Fractions, strings, and exponential notation are rejected (INVALID_AMOUNT); ≥ 1; ≤ 100000000
reasonstring≤ 200 characters
Responses
  • 200Repeat with the same Idempotency-Key: the same operation in its current state; header Idempotent-Replayed: true
  • 201Refund accepted by Kaspi
  • 202Result unknown
  • 409Error
  • 422Declined by Kaspi
  • 503Error
GET/api/v1/payments/{id}/refundspayments:read

Payment refunds and the refunded amount

Request body fields
FieldTypeConstraints
id *path: stringuuid
Responses
  • 200List
  • 404Error
POST/api/v1/payment-linkspayments:createIdempotency-Key

Payment link (/l/code): one order or reusable, a fixed amount or an amount the buyer enters (min/max), expiry, payment limit. Each payer of a reusable link gets a new payment

Request body fields
FieldTypeConstraints
title *string≤ 120 characters
descriptionstring≤ 200 characters
amount_mode"fixed" | "open"
amountintegerA whole number of tenge (JSON number). Fractions, strings, and exponential notation are rejected (INVALID_AMOUNT); ≥ 1; ≤ 100000000
min_amountintegerA whole number of tenge (JSON number). Fractions, strings, and exponential notation are rejected (INVALID_AMOUNT); ≥ 1; ≤ 100000000
max_amountintegerA whole number of tenge (JSON number). Fractions, strings, and exponential notation are rejected (INVALID_AMOUNT); ≥ 1; ≤ 100000000
reusablebooleandefault false
max_paymentsinteger≥ 1
expires_atstringdate-time
success_urlstringuri
metadataobjectYour data (keys: Latin letters, digits, _ . -). Returned in the API and webhooks, never sent to the bank. Up to 2 KB
Responses
  • 201Link
  • 400Error
POST/api/v1/payment-links/{id}/revokepayments:createIdempotency-Key

Disable a link (payments already started finish as usual)

Request body fields
FieldTypeConstraints
id *path: stringuuid
Responses
  • 200Link
  • 404Error
GET/api/v1/customerspayments:read

Seller customers (search q, tag, overdue=1) with a summary: paid, outstanding, overdue invoices. Live token only

No request body is required.

Responses
  • 200OK
  • 201Created
  • 400Error
  • 404Error
  • 409Error
POST/api/v1/customerspayments:createIdempotency-Key

Customer: name, phone (for a Kaspi invoice; stored encrypted), email, tags, external_id, channels (notification channel order)

No request body is required.

Responses
  • 200OK
  • 201Created
  • 400Error
  • 404Error
  • 409Error
GET/api/v1/customers/{id}payments:read

A customer, their invoices (state based on the bank-confirmed payment), and schedules

Request body fields
FieldTypeConstraints
id *path: stringuuid
Responses
  • 200OK
  • 201Created
  • 400Error
  • 404Error
  • 409Error
PATCH/api/v1/customers/{id}payments:create

Update a customer

Request body fields
FieldTypeConstraints
id *path: stringuuid
Responses
  • 200OK
  • 201Created
  • 400Error
  • 404Error
  • 409Error
POST/api/v1/customers/{id}/invoicespayments:createIdempotency-Key

Invoice a customer now: method remote_invoice (Kaspi invoice to a phone) or payment_link; amount/description or template_id; due_days

Request body fields
FieldTypeConstraints
id *path: stringuuid
Responses
  • 200OK
  • 201Created
  • 400Error
  • 404Error
  • 409Error
GET/api/v1/customer-invoices/{id}payments:read

A customer invoice: issue_state (issuance) and state (open, paid, expired, cancelled, failed) from the payment

Request body fields
FieldTypeConstraints
id *path: stringuuid
Responses
  • 200OK
  • 201Created
  • 400Error
  • 404Error
  • 409Error
GET/api/v1/schedulespayments:read

Recurring invoices (customer_id filter)

No request body is required.

Responses
  • 200OK
  • 201Created
  • 400Error
  • 404Error
  • 409Error
POST/api/v1/schedulespayments:createIdempotency-Key

Recurring invoice: cadence daily | weekly (weekday 1-7) | monthly (month_day 1-28 or last) | custom (custom_dates), every_n, local_hour (Almaty), start_date, end_date, missed_policy latest | all, reminder_hours, due_days. Each period is one regular invoice; there is no automatic charge

No request body is required.

Responses
  • 200OK
  • 201Created
  • 400Error
  • 404Error
  • 409Error
GET/api/v1/schedules/{id}payments:read

A schedule and its invoices by period

Request body fields
FieldTypeConstraints
id *path: stringuuid
Responses
  • 200OK
  • 201Created
  • 400Error
  • 404Error
  • 409Error
POST/api/v1/schedules/{id}/pausepayments:createIdempotency-Key

Pause a schedule

Request body fields
FieldTypeConstraints
id *path: stringuuid
Responses
  • 200OK
  • 201Created
  • 400Error
  • 404Error
  • 409Error
POST/api/v1/schedules/{id}/resumepayments:createIdempotency-Key

Resume (periods missed during the pause are not invoiced)

Request body fields
FieldTypeConstraints
id *path: stringuuid
Responses
  • 200OK
  • 201Created
  • 400Error
  • 404Error
  • 409Error
POST/api/v1/schedules/{id}/cancelpayments:create

Cancel a schedule

Request body fields
FieldTypeConstraints
id *path: stringuuid
Responses
  • 200OK
  • 201Created
  • 400Error
  • 404Error
  • 409Error
POST/api/v1/bulk-invoicespayments:createIdempotency-Key

Bulk invoices: rows [{customer_id | name+phone, amount, description, order_id}] or csv; method; due_days. Invalid rows go to rejected_rows. Issuance runs in the background with rate limiting

No request body is required.

Responses
  • 200OK
  • 201Created
  • 400Error
  • 404Error
  • 409Error
GET/api/v1/bulk-invoices/{id}payments:read

An invoice batch: status, counters by state, rows

Request body fields
FieldTypeConstraints
id *path: stringuuid
Responses
  • 200OK
  • 201Created
  • 400Error
  • 404Error
  • 409Error
GET/api/v1/reports/paymentspayments:read

Accounting export (1C): bank-confirmed payments of the resource for a period (from, to are Almaty dates), refunds, Kaspi operation number, metadata; format=csv gives CSV for Excel/1C. fiscal_receipt is always empty because no fiscal provider is connected. Live token only

No request body is required.

Responses
  • 200OK
  • 400Error
GET/api/v1/reports/reconciliationpayments:read

Reconciliation by day and cashier: paid, refunded, net; open payments and payments needing review

No request body is required.

Responses
  • 200OK
  • 400Error

Error codes

JSON
{ "error": { "code": "VALIDATION_FAILED", "message": "…", "request_id": "…", "fields": { "amount": "invalid" } } }
Error codes
HTTPcode
410LINK_INACTIVEThe payment link is disabled, expired, already paid, or has reached its limit (error.reason).
503REFUNDS_NOT_ENABLEDKaspi refunds are not enabled yet: refund the money in the Kaspi Pay app.
409REFUND_NOT_ALLOWEDOnly a payment made through Kaspi QR can be refunded.
409REFUND_AMOUNT_EXCEEDEDThe refund amount exceeds the remaining balance (error.refundable_amount).
409REFUND_UNRESOLVEDThe payment has a refund with an unknown result; check it in Kaspi Pay.
400CONFIRMATION_REQUIREDExplicit confirmation of the financial operation is required.
409SCHEDULE_STATEThe action is not available in the current schedule status.
400IMPORT_INVALIDThe file or row list is invalid (row details are in the response).
409CHANNEL_NOT_CONFIGUREDThe notification channel is not connected.
400VALIDATION_FAILEDInvalid request field (details in error.fields).
400INVALID_AMOUNTThe amount must be a whole number of tenge from 1 to 100,000,000.
400INVALID_PHONEInvalid buyer phone number.
400IDEMPOTENCY_KEY_REQUIREDThe Idempotency-Key header is missing or invalid.
401API_TOKEN_MISSINGThe Authorization header is missing.
401API_TOKEN_INVALIDInvalid token (or the token was sent in the URL).
401API_TOKEN_REVOKEDThe token has been revoked.
401API_TOKEN_EXPIREDThe token has expired.
402SUBSCRIPTION_INACTIVEThe cashier subscription is inactive: new payments are unavailable.
403API_TOKEN_SCOPEThe token lacks the required permission.
403ACCOUNT_INACTIVEThe seller account is suspended.
404NOT_FOUNDNo such operation for the token’s resource.
409ORDER_ALREADY_EXISTSThe order was already created with a different key (error.payment_id).
409IDEMPOTENCY_KEY_REUSEDThe same key was used with different data.
409CASHIER_NOT_CONNECTEDThe cashier is not connected to Kaspi.
409PAYMENT_STATEThe action is not available in the current status.
422PROVIDER_REJECTEDThe bank declined; the operation was not created.
429RATE_LIMITEDRate limit reached (Retry-After header).
503GATEWAY_UNAVAILABLETemporary: retry with the same Idempotency-Key.

Webhooks

payment.createdpayment.paidpayment.failedpayment.expiredpayment.cancelledpayment.needs_reviewremote_invoice.createdremote_invoice.paidremote_invoice.cancelled
Event example
{
  "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": "…"
  }
}
Signature verification (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'));
  });
}