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.
Cancel an unpaid remote invoice (cancelled only after Kaspi confirms)
Request body fields
Field
Type
Constraints
id *
path: string
uuid
cURL
curl -X POST "https://bankemes.example/api/v1/invoices/remote/{id}/cancel" \
-H "Authorization: Bearer bms_live_XXXXXXXX_your-secret-token"
JavaScript
const res = await fetch('https://bankemes.example/api/v1/invoices/remote/{id}/cancel', {
method: 'POST',
headers: { Authorization: `Bearer ${process.env.BANKEMES_TOKEN}` },
});
const data = await res.json();
if (!res.ok) throw new Error(`${data.error.code}: ${data.error.message}`);
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
Field
Type
Constraints
id *
path: string
uuid
Responses
200Payment
404Error
409Error
GET/api/v1/payments/{id}/eventspayments:read
Payment status history (type, from_status, to_status, at)
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
Field
Type
Constraints
id *
path: string
uuid
amount
integer
A whole number of tenge (JSON number). Fractions, strings, and exponential notation are rejected (INVALID_AMOUNT); ≥ 1; ≤ 100000000
reason
string
≤ 200 characters
Responses
200Repeat with the same Idempotency-Key: the same operation in its current state; header Idempotent-Replayed: true
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
Field
Type
Constraints
title *
string
≤ 120 characters
description
string
≤ 200 characters
amount_mode
"fixed" | "open"
amount
integer
A whole number of tenge (JSON number). Fractions, strings, and exponential notation are rejected (INVALID_AMOUNT); ≥ 1; ≤ 100000000
min_amount
integer
A whole number of tenge (JSON number). Fractions, strings, and exponential notation are rejected (INVALID_AMOUNT); ≥ 1; ≤ 100000000
max_amount
integer
A whole number of tenge (JSON number). Fractions, strings, and exponential notation are rejected (INVALID_AMOUNT); ≥ 1; ≤ 100000000
reusable
boolean
default false
max_payments
integer
≥ 1
expires_at
string
date-time
success_url
string
uri
metadata
object
Your data (keys: Latin letters, digits, _ . -). Returned in the API and webhooks, never sent to the bank. Up to 2 KB
Responses
201Link
400Error
GET/api/v1/payment-linkspayments:read
Payment links of the token’s resource
No request body is required.
Responses
200List
GET/api/v1/payment-links/{id}payments:read
A payment link (active, inactive_reason, paid_count)
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
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
Field
Type
Constraints
id *
path: string
uuid
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