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

Быстрый старт

Base URL: https://api.tolepay.kz/v1. Для первой интеграции используйте test-ключ и /sandbox, где запросы никогда не уходят в Kaspi.

Создайте sandbox-подключение

В кабинете откройте «API-ключи» → «Создать тестовый ключ». Тестовое подключение подготовится автоматически, Kaspi и платная подписка не нужны.

Создайте test API-ключ

Выберите набор прав или настройте их вручную. Сохраните ключ, ID подключения и готовые запросы. JWT для тестирования не нужен; GET /api-key показывает права и подключения.

Создайте счёт или QR

Передайте Bearer-ключ, X-Tole-Connection-Id и уникальный Idempotency-Key.

Смоделируйте оплату

Вызовите simulate со статусом paid и проверьте свой webhook-обработчик.

Переключитесь на live

Замените test-ключ и /sandbox routes на live-ключ и live routes. Test ID не переносятся в live.

Как подготовить кассира Kaspi

Авторизация и общие заголовки

Платёжные endpoints вызываются только с вашего backend. Никогда не передавайте tole_sk_* в браузер, мобильное приложение, публичный репозиторий или frontend-логи.

`Authorization`

Обязательный. Bearer tole_sk_live_v1… для live или Bearer tole_sk_test_v1… для sandbox.

`Content-Type`

application/json для запросов с body.

`X-Tole-Connection-Id`

UUID подключения. В live необязателен при наличии основного подключения; в sandbox обязателен всегда.

`Idempotency-Key`

Обязателен для create/cancel/refund. 1–100 символов: A–Z, a–z, 0–9, точка, _, :, -. Один бизнес-запрос — один ключ.

Права ключа проверяются для выбранного подключения. Grant на другое подключение не даёт доступа. Wildcard-права не поддерживаются.

Read

120 / min

GET и provider reads

Lookup

60 / min

client-info

Mutation

30 / min

create, cancel, refund

Live payment API

Все маршруты ниже добавляются к https://api.tolepay.kz/v1. operationId и paymentIntentId — локальные UUID Tole; приватные идентификаторы Kaspi наружу не возвращаются.

POST/invoices/client-infoПроверить получателя счёта

Проверяет, может ли Kaspi выставить счёт указанному номеру. ФИО и полный телефон клиента наружу не возвращаются.

Авторизация: Bearer API keyPermission: invoice:readHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`X-Tole-Connection-Id`	header	`string`	Нет	UUID live-подключения; можно не передавать при настроенном основном подключении.
`phoneNumber`	body	`string`	Да	Казахстанский номер: +7 и 10 цифр.

Набор safe-полей зависит от ответа Kaspi: available, canCreateInvoice, eligible, exists, isAvailable, status.

Пример запроса

curl https://api.tolepay.kz/v1/invoices/client-info \
  -H "Authorization: Bearer $TOLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phoneNumber":"+77001234567"}'

200 OK · Пример ответа

{
  "ok": true,
  "data": { "eligible": true }
}

POST/invoicesСоздать счёт по номеру

Создаёт live-счёт Kaspi. Возвращённый data.id — локальный UUID Tole для следующих запросов.

Авторизация: Bearer API keyPermission: invoice:createHTTP: 201 Created

Поле	Где	Тип	Обязательно	Описание
`X-Tole-Connection-Id`	header	`string`	Нет	UUID live-подключения; можно не передавать при настроенном основном подключении.
`Idempotency-Key`	header	`string`	Да	Уникальный ключ мутации. Повторяйте тот же запрос с тем же ключом.
`phoneNumber`	body	`string`	Да	+7 и 10 цифр.
`amount`	body	`integer`	Да	Сумма в KZT: 1–100 000 000.
`comment`	body	`string`	Нет	Необязательно, максимум 200 символов.

receiptUrl и orderNumber необязательны и присутствуют только при валидном ответе Kaspi.

Пример запроса

curl https://api.tolepay.kz/v1/invoices \
  -X POST \
  -H "Authorization: Bearer $TOLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1024-invoice-v1" \
  -d '{"phoneNumber":"+77001234567","amount":5000,"comment":"Order 1024"}'

201 Created · Пример ответа

{
  "ok": true,
  "data": {
    "id": "d7dfb407-0e4c-4cc2-9d31-26d9f696cb27",
    "kind": "invoice",
    "status": "created",
    "amount": 5000,
    "clientPhoneLast4": "4567",
    "receiptUrl": "https://…",
    "orderNumber": "…"
  },
  "commandId": "d7dfb407-0e4c-4cc2-9d31-26d9f696cb27",
  "replayed": false
}

GET/invoices/historyПолучить историю счетов

Возвращает безопасную историю счетов выбранного подключения.

Авторизация: Bearer API keyPermission: invoice:readHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`X-Tole-Connection-Id`	header	`string`	Нет	UUID live-подключения; можно не передавать при настроенном основном подключении.

Provider-поля фильтруются; приватные Kaspi ID заменяются локальными operationId.

Пример запроса

curl https://api.tolepay.kz/v1/invoices/history \
  -H "Authorization: Bearer $TOLE_API_KEY"

200 OK · Пример ответа

{
  "ok": true,
  "data": { "items": [{ "operationId": "uuid", "amount": 5000, "status": "Processed", "date": "…" }] }
}

GET/invoices/{operationId}Получить детали счёта

Читает актуальные детали у провайдера и обновляет наблюдаемый статус payment intent.

Авторизация: Bearer API keyPermission: invoice:readHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`X-Tole-Connection-Id`	header	`string`	Нет	UUID live-подключения; можно не передавать при настроенном основном подключении.
`operationId`	path	`uuid`	Да	Локальный owner-scoped UUID операции Tole.

Пример запроса

curl https://api.tolepay.kz/v1/invoices/$OPERATION_ID \
  -H "Authorization: Bearer $TOLE_API_KEY"

200 OK · Пример ответа

{
  "ok": true,
  "data": { "amount": 5000, "currency": "KZT", "status": "Processed" }
}

POST/invoices/{operationId}/cancelОтменить счёт

Отменяет ранее созданный счёт. Body — пустой JSON-объект.

Авторизация: Bearer API keyPermission: invoice:cancelHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`X-Tole-Connection-Id`	header	`string`	Нет	UUID live-подключения; можно не передавать при настроенном основном подключении.
`Idempotency-Key`	header	`string`	Да	Уникальный ключ мутации. Повторяйте тот же запрос с тем же ключом.
`operationId`	path	`uuid`	Да	Локальный owner-scoped UUID операции Tole.

Пример запроса

curl https://api.tolepay.kz/v1/invoices/$OPERATION_ID/cancel \
  -X POST \
  -H "Authorization: Bearer $TOLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1024-cancel-v1" \
  -d '{}'

200 OK · Пример ответа

{
  "ok": true,
  "data": { "operationId": "uuid", "status": "cancelled" },
  "commandId": "uuid",
  "replayed": false
}

POST/qrСоздать динамический QR

Создаёт QR для оплаты и возвращает paymentUrl и исходный qrToken.

Авторизация: Bearer API keyPermission: qr:createHTTP: 201 Created

Поле	Где	Тип	Обязательно	Описание
`X-Tole-Connection-Id`	header	`string`	Нет	UUID live-подключения; можно не передавать при настроенном основном подключении.
`Idempotency-Key`	header	`string`	Да	Уникальный ключ мутации. Повторяйте тот же запрос с тем же ключом.
`amount`	body	`integer`	Да	Сумма KZT: 1–100 000 000.
`latitude`	body	`number`	Нет	Необязательно, −90…90; только вместе с longitude.
`longitude`	body	`number`	Нет	Необязательно, −180…180; только вместе с latitude.

expiresAt и receiptUrl необязательны. paymentUrl и qrToken всегда HTTPS.

Пример запроса

curl https://api.tolepay.kz/v1/qr \
  -X POST \
  -H "Authorization: Bearer $TOLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1024-qr-v1" \
  -d '{"amount":5000}'

201 Created · Пример ответа

{
  "ok": true,
  "data": {
    "id": "uuid", "kind": "qr", "status": "created", "amount": 5000,
    "paymentUrl": "https://…", "qrToken": "https://qr.kaspi.kz/…",
    "expiresAt": "…", "receiptUrl": "https://…"
  },
  "commandId": "uuid",
  "replayed": false
}

GET/qr/{operationId}Получить детали QR

Читает текущий статус QR у провайдера.

Авторизация: Bearer API keyPermission: qr:readHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`X-Tole-Connection-Id`	header	`string`	Нет	UUID live-подключения; можно не передавать при настроенном основном подключении.
`operationId`	path	`uuid`	Да	Локальный owner-scoped UUID операции Tole.

Пример запроса

curl https://api.tolepay.kz/v1/qr/$OPERATION_ID \
  -H "Authorization: Bearer $TOLE_API_KEY"

200 OK · Пример ответа

{
  "ok": true,
  "data": { "amount": 5000, "currency": "KZT", "status": "Processed" }
}

GET/history/operationsПолучить историю операций

История до указанной календарной даты UTC с cursor следующей страницы.

Авторизация: Bearer API keyPermission: history:readHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`X-Tole-Connection-Id`	header	`string`	Нет	UUID live-подключения; можно не передавать при настроенном основном подключении.
`endDate`	query	`date`	Да	Обязательно: YYYY-MM-DD, включительно, UTC.
`lastTransactionDate`	query	`string`	Нет	Cursor из предыдущего ответа.
`statementPeriodCode`	query	`integer`	Нет	Неотрицательный код периода.

Пример запроса

curl "https://api.tolepay.kz/v1/history/operations?endDate=2026-08-23" \
  -H "Authorization: Bearer $TOLE_API_KEY"

200 OK · Пример ответа

{
  "ok": true,
  "data": {
    "items": [{ "operationId": "uuid", "amount": 5000, "type": "Payment", "status": "Processed" }],
    "lastTransactionDate": "…", "hasMore": false
  }
}

GET/history/operations/{operationId}Получить операцию из истории

Безопасные детали операции по локальному UUID.

Авторизация: Bearer API keyPermission: history:readHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`X-Tole-Connection-Id`	header	`string`	Нет	UUID live-подключения; можно не передавать при настроенном основном подключении.
`operationId`	path	`uuid`	Да	Локальный owner-scoped UUID операции Tole.
`operationMethod`	query	`integer`	Нет	Необязательный неотрицательный код метода.

Пример запроса

curl "https://api.tolepay.kz/v1/history/operations/$OPERATION_ID?operationMethod=0" \
  -H "Authorization: Bearer $TOLE_API_KEY"

200 OK · Пример ответа

{
  "ok": true,
  "data": { "operationId": "uuid", "amount": 5000, "status": "Processed" }
}

POST/refundsСоздать возврат

Полный или частичный возврат оплаченного удалённого счёта или QR текущего подключения.

Авторизация: Bearer API keyPermission: refund:createHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`X-Tole-Connection-Id`	header	`string`	Нет	UUID live-подключения; можно не передавать при настроенном основном подключении.
`Idempotency-Key`	header	`string`	Да	Уникальный ключ мутации. Повторяйте тот же запрос с тем же ключом.
`operationId`	body	`uuid`	Да	Локальный UUID invoice/QR payment intent.
`returnAmount`	body	`integer`	Да	KZT: 1–100 000 000, не больше доступного остатка.

Пример запроса

curl https://api.tolepay.kz/v1/refunds \
  -X POST \
  -H "Authorization: Bearer $TOLE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: refund-order-1024-v1" \
  -d '{"operationId":"uuid","returnAmount":1500}'

200 OK · Пример ответа

{
  "ok": true,
  "data": { "operationId": "uuid", "status": "refund_accepted", "returnAmount": 1500 },
  "commandId": "uuid", "replayed": false
}

GET/payment-intents/invoices/{paymentIntentId}Получить сохранённый статус счёта

Читает состояние из надёжного ledger Tole для reconciliation.

Авторизация: Bearer API keyPermission: invoice:readHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`X-Tole-Connection-Id`	header	`string`	Нет	UUID live-подключения; можно не передавать при настроенном основном подключении.
`paymentIntentId`	path	`uuid`	Да	UUID платёжного намерения Tole.

Пример запроса

curl https://api.tolepay.kz/v1/payment-intents/invoices/$PAYMENT_INTENT_ID \
  -H "Authorization: Bearer $TOLE_API_KEY"

200 OK · Пример ответа

{
  "ok": true,
  "data": {
    "id": "uuid", "kind": "invoice", "status": "paid", "amount": 5000,
    "refundedAmount": 0, "currency": "KZT", "revision": 3,
    "source": "scheduled_invoice", "recurringInvoiceId": "uuid",
    "occurrenceId": "uuid", "attemptNumber": 1,
    "createdAt": "2026-08-23T10:00:00.000Z", "updatedAt": "2026-08-23T10:01:00.000Z",
    "paidAt": "2026-08-23T10:01:00.000Z", "terminalAt": null, "lastReconciledAt": "…"
  }
}

GET/payment-intents/qr/{paymentIntentId}Получить сохранённый статус QR

Durable payment-intent контракт для QR.

Авторизация: Bearer API keyPermission: qr:readHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`X-Tole-Connection-Id`	header	`string`	Нет	UUID live-подключения; можно не передавать при настроенном основном подключении.
`paymentIntentId`	path	`uuid`	Да	UUID платёжного намерения Tole.

Пример запроса

curl https://api.tolepay.kz/v1/payment-intents/qr/$PAYMENT_INTENT_ID \
  -H "Authorization: Bearer $TOLE_API_KEY"

200 OK · Пример ответа

{
  "ok": true,
  "data": {
    "id": "uuid", "kind": "qr", "status": "pending", "amount": 5000,
    "currency": "KZT", "revision": 1, "source": null,
    "recurringInvoiceId": null, "occurrenceId": null, "attemptNumber": null
  }
}

GET/commands/{commandId}Проверить идемпотентную команду

Проверяет create/cancel/refund после 202, сетевого разрыва или повтора.

Авторизация: Bearer API keyHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`commandId`	path	`uuid`	Да	UUID из commandId или Location.

Команда сама определяет connection и permission. Чужой commandId возвращает 404.

Пример запроса

curl https://api.tolepay.kz/v1/commands/$COMMAND_ID \
  -H "Authorization: Bearer $TOLE_API_KEY"

200 OK · Пример ответа

{
  "ok": true,
  "data": {
    "commandId": "uuid", "status": "succeeded", "responseStatus": 201,
    "result": { "ok": true, "data": { "id": "uuid" }, "commandId": "uuid" },
    "updatedAt": "2026-08-23T10:00:01.000Z"
  }
}

Автосчета

Автосчёт автоматически выставляет обычный удалённый счёт Kaspi по typed-расписанию. Это не автосписание: покупатель сам решает, оплачивать счёт или нет.

Правило хранит конкретный connectionId, номер, сумму, комментарий, timezone, условия завершения и retry policy. API-key ответы показывают только phoneLast4 и commentPresent; полный номер и текст доступны владельцу только через JWT API кабинета.

POST/recurring-invoices/preview

API key · Следующие 1–20 запусков; ничего не сохраняет

POST/recurring-invoices

recurring_invoice:create + invoice:create · Создать правило · Idempotency-Key

GET/recurring-invoices

recurring_invoice:read · Правила всех доступных connections

GET/recurring-invoices/{recurringInvoiceId}

recurring_invoice:read · Безопасная проекция правила

PATCH/recurring-invoices/{recurringInvoiceId}

recurring_invoice:update + invoice:create · Изменить только будущие запуски

POST/recurring-invoices/{recurringInvoiceId}/pause

recurring_invoice:update · Приостановить будущие запуски

POST/recurring-invoices/{recurringInvoiceId}/resume

recurring_invoice:update + invoice:create · Возобновить расписание и перепривязать execution key

POST/recurring-invoices/{recurringInvoiceId}/run

recurring_invoice:trigger + invoice:create · Поставить run-now в очередь · Idempotency-Key

DELETE/recurring-invoices/{recurringInvoiceId}?expectedRevision=N

recurring_invoice:delete · Архивировать, сохранив историю

GET/recurring-invoices/{recurringInvoiceId}/occurrences

recurring_invoice:read · Список запусков

GET/recurring-invoices/{recurringInvoiceId}/occurrences/{occurrenceId}

recurring_invoice:read · Запуск и его attempts

Расписание без cron

Передавайте monthly, interval, weekly или once и IANA timezone. Локальное время HH:mm и YYYY-MM-DDTHH:mm интерпретируется именно в этой timezone; preview возвращает UTC instants для показа человеку.

Typed schedule examples

// Каждый месяц 27-го числа в 10:00
{"kind":"monthly","dayOfMonth":27,"time":"10:00","shortMonthPolicy":"last_day"}

// Каждые две недели с локальной точки отсчёта
{"kind":"interval","every":2,"unit":"week","anchorAt":"2026-09-01T09:30"}

// Каждые десять дней
{"kind":"interval","every":10,"unit":"day","anchorAt":"2026-09-01T10:00"}

// Каждый понедельник и пятницу в 09:00
{"kind":"weekly","everyWeeks":1,"weekdays":[1,5],"time":"09:00"}

// Один раз в локальном времени правила
{"kind":"once","runAt":"2026-09-01T10:00"}

weekdays использует ISO-нумерацию: понедельник = 1, воскресенье = 7. Weekly response содержит стабильный локальный anchorDate в формате YYYY-MM-DD; сохраняйте его при редактировании cadence раз в N недель. Для 29–31 числа last_day переносит запуск на последний день короткого месяца, а skip пропускает такой месяц. anchorAt и runAt имеют строгий формат YYYY-MM-DDTHH:mm без секунд и offset.

POST/recurring-invoices/previewПредпросмотр расписания

Рассчитывает следующие 1–20 UTC instants без сохранения правила и без обращения в Kaspi.

Авторизация: Bearer API keyHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`schedule`	body	`monthly \| interval \| weekly \| once`	Да	Typed schedule; cron-строка не принимается.
`timezone`	body	`IANA timezone`	Да	Например Asia/Almaty.
`startsAt`	body	`RFC 3339 date-time`	Нет	Необязательная нижняя граница окна.
`endsAt`	body	`RFC 3339 date-time`	Нет	Необязательная верхняя граница окна.
`count`	body	`integer 1..20`	Нет	Количество дат; по умолчанию 5.

Ответ содержит UTC instants. Показывайте их пользователю в timezone правила.

Пример запроса

curl https://api.tolepay.kz/v1/recurring-invoices/preview \
  -X POST \
  -H "Authorization: Bearer $TOLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule":{"kind":"monthly","dayOfMonth":27,"time":"10:00","shortMonthPolicy":"last_day"},
    "timezone":"Asia/Almaty","count":5
  }'

200 OK · Пример ответа

{
  "nextRuns": [
    "2026-09-27T05:00:00.000Z",
    "2026-10-27T05:00:00.000Z"
  ]
}

POST/recurring-invoicesСоздать автосчёт

Создаёт durable-правило и навсегда привязывает его к выбранному сейчас live connection.

Авторизация: Bearer API keyPermission: recurring_invoice:create + invoice:createHTTP: 201 Created

Поле	Где	Тип	Обязательно	Описание
`X-Tole-Connection-Id`	header	`string`	Нет	UUID live-подключения; можно не передавать при настроенном основном подключении.
`Idempotency-Key`	header	`string`	Да	Уникальный ключ мутации. Повторяйте тот же запрос с тем же ключом.
`name`	body	`string 1..100`	Да	Понятное внутреннее название.
`phoneNumber`	body	`string`	Да	Казахстанский номер: +7/7 и 10 следующих цифр.
`amount`	body	`integer 1..100000000`	Да	Сумма одного счёта в KZT.
`comment`	body	`string <= 200`	Нет	Необязательный комментарий обычного удалённого счёта Kaspi.
`schedule`	body	`schedule union`	Да	monthly \| interval \| weekly \| once.
`timezone`	body	`IANA timezone`	Да	Timezone для wall-clock полей расписания.
`startsAt / endsAt`	body	`RFC 3339 date-time`	Нет	Необязательное окно исполнения.
`maxOccurrences`	body	`integer 1..100000`	Нет	Необязательное максимальное число запусков.
`retryPolicy`	body	`{ delays: ISO duration[] }`	Нет	До 5 задержек в точном переданном порядке; каждая PT1S..P30D.
`misfirePolicy`	body	`run_once \| skip`	Нет	По умолчанию run_once.

Без X-Tole-Connection-Id сервер один раз выбирает default и сохраняет его UUID. Смена default не переносит созданное правило.

Пример запроса

curl https://api.tolepay.kz/v1/recurring-invoices \
  -X POST \
  -H "Authorization: Bearer $TOLE_API_KEY" \
  -H "Idempotency-Key: customer-42-monthly-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "name":"Ежемесячная подписка","phoneNumber":"77001234567","amount":15000,
    "comment":"За сентябрь",
    "schedule":{"kind":"monthly","dayOfMonth":27,"time":"10:00","shortMonthPolicy":"last_day"},
    "timezone":"Asia/Almaty","retryPolicy":{"delays":["PT6H","PT1H","PT15M"]},
    "misfirePolicy":"run_once"
  }'

201 Created · Пример ответа

{
  "id": "2d229044-8645-4e8b-b3fc-e0d6a9fe4184",
  "name": "Ежемесячная подписка",
  "phoneLast4": "4567",
  "amount": 15000,
  "commentPresent": true,
  "connectionId": "7a67d6bd-5daf-47af-b899-fdb8b7db4d63",
  "schedule": {
    "kind": "monthly", "dayOfMonth": 27, "time": "10:00",
    "shortMonthPolicy": "last_day"
  },
  "timezone": "Asia/Almaty",
  "startsAt": null,
  "endsAt": null,
  "maxOccurrences": null,
  "occurrenceCount": 0,
  "nextRunAt": "2026-09-27T05:00:00.000Z",
  "status": "active",
  "misfirePolicy": "run_once",
  "retryPolicy": { "delays": ["PT6H", "PT1H", "PT15M"] },
  "revision": 1,
  "lastRunAt": null,
  "createdAt": "2026-08-24T10:00:00.000Z",
  "updatedAt": "2026-08-24T10:00:00.000Z",
  "archivedAt": null
}

GET/recurring-invoicesПолучить список правил

Возвращает правила всех connections, для которых ключ имеет read grant. Без status архив не включается; передайте status=archived явно.

Авторизация: Bearer API keyPermission: recurring_invoice:readHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`cursor`	query	`string`	Нет	Opaque cursor предыдущей страницы.
`limit`	query	`integer 1..100`	Нет	Размер страницы.
`status`	query	`rule status`	Нет	Необязательный фильтр по статусу.

Пример запроса

curl "https://api.tolepay.kz/v1/recurring-invoices?limit=20&status=active" \
  -H "Authorization: Bearer $TOLE_API_KEY"

200 OK · Пример ответа

{
  "recurringInvoices": [{
  "id": "2d229044-8645-4e8b-b3fc-e0d6a9fe4184",
  "name": "Ежемесячная подписка",
  "phoneLast4": "4567",
  "amount": 15000,
  "commentPresent": true,
  "connectionId": "7a67d6bd-5daf-47af-b899-fdb8b7db4d63",
  "schedule": {
    "kind": "monthly", "dayOfMonth": 27, "time": "10:00",
    "shortMonthPolicy": "last_day"
  },
  "timezone": "Asia/Almaty",
  "startsAt": null,
  "endsAt": null,
  "maxOccurrences": null,
  "occurrenceCount": 0,
  "nextRunAt": "2026-09-27T05:00:00.000Z",
  "status": "active",
  "misfirePolicy": "run_once",
  "retryPolicy": { "delays": ["PT6H", "PT1H", "PT15M"] },
  "revision": 1,
  "lastRunAt": null,
  "createdAt": "2026-08-24T10:00:00.000Z",
  "updatedAt": "2026-08-24T10:00:00.000Z",
  "archivedAt": null
}],
  "nextCursor": null
}

GET/recurring-invoices/{recurringInvoiceId}Получить правило

Возвращает masked projection без полного телефона и текста комментария.

Авторизация: Bearer API keyPermission: recurring_invoice:readHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`recurringInvoiceId`	path	`uuid`	Да	Owner-scoped UUID правила автосчёта.

Пример запроса

curl https://api.tolepay.kz/v1/recurring-invoices/$RECURRING_INVOICE_ID \
  -H "Authorization: Bearer $TOLE_API_KEY"

200 OK · Пример ответа

{
  "id": "2d229044-8645-4e8b-b3fc-e0d6a9fe4184",
  "name": "Ежемесячная подписка",
  "phoneLast4": "4567",
  "amount": 15000,
  "commentPresent": true,
  "connectionId": "7a67d6bd-5daf-47af-b899-fdb8b7db4d63",
  "schedule": {
    "kind": "monthly", "dayOfMonth": 27, "time": "10:00",
    "shortMonthPolicy": "last_day"
  },
  "timezone": "Asia/Almaty",
  "startsAt": null,
  "endsAt": null,
  "maxOccurrences": null,
  "occurrenceCount": 0,
  "nextRunAt": "2026-09-27T05:00:00.000Z",
  "status": "active",
  "misfirePolicy": "run_once",
  "retryPolicy": { "delays": ["PT6H", "PT1H", "PT15M"] },
  "revision": 1,
  "lastRunAt": null,
  "createdAt": "2026-08-24T10:00:00.000Z",
  "updatedAt": "2026-08-24T10:00:00.000Z",
  "archivedAt": null
}

PATCH/recurring-invoices/{recurringInvoiceId}Изменить будущие запуски

Обновляет только будущую конфигурацию; существующие occurrences и payment intents не переписываются.

Авторизация: Bearer API keyPermission: recurring_invoice:update + invoice:createHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`recurringInvoiceId`	path	`uuid`	Да	Owner-scoped UUID правила автосчёта.
`expectedRevision`	body	`integer >= 1`	Да	Revision из последнего GET; защищает от потерянных изменений.
`изменяемые поля`	body	`partial create body`	Нет	Минимум одно поле кроме expectedRevision. null очищает comment, startsAt, endsAt, maxOccurrences или retryPolicy.

Stale revision возвращает 409 RECURRING_INVOICE_CONCURRENT_MODIFICATION: перечитайте правило и повторите решение на свежей версии.

Пример запроса

curl https://api.tolepay.kz/v1/recurring-invoices/$RECURRING_INVOICE_ID \
  -X PATCH \
  -H "Authorization: Bearer $TOLE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expectedRevision":1,"amount":17500,"retryPolicy":null}'

200 OK · Пример ответа

{
  "id": "2d229044-8645-4e8b-b3fc-e0d6a9fe4184",
  "name": "Ежемесячная подписка",
  "phoneLast4": "4567",
  "amount": 15000,
  "commentPresent": true,
  "connectionId": "7a67d6bd-5daf-47af-b899-fdb8b7db4d63",
  "schedule": {
    "kind": "monthly", "dayOfMonth": 27, "time": "10:00",
    "shortMonthPolicy": "last_day"
  },
  "timezone": "Asia/Almaty",
  "startsAt": null,
  "endsAt": null,
  "maxOccurrences": null,
  "occurrenceCount": 0,
  "nextRunAt": "2026-09-27T05:00:00.000Z",
  "status": "active",
  "misfirePolicy": "run_once",
  "retryPolicy": { "delays": ["PT6H", "PT1H", "PT15M"] },
  "revision": 1,
  "lastRunAt": null,
  "createdAt": "2026-08-24T10:00:00.000Z",
  "updatedAt": "2026-08-24T10:00:00.000Z",
  "archivedAt": null
}

POST/recurring-invoices/{recurringInvoiceId}/pauseПриостановить правило

Останавливает будущие плановые запуски, не удаляя историю.

Авторизация: Bearer API keyPermission: recurring_invoice:updateHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`recurringInvoiceId`	path	`uuid`	Да	Owner-scoped UUID правила автосчёта.
`expectedRevision`	body	`integer >= 1`	Да	Тек текущая revision.

Пример запроса

curl https://api.tolepay.kz/v1/recurring-invoices/$RECURRING_INVOICE_ID/pause \
  -X POST -H "Authorization: Bearer $TOLE_API_KEY" \
  -H "Content-Type: application/json" -d '{"expectedRevision":1}'

200 OK · Пример ответа

{
  "id": "2d229044-8645-4e8b-b3fc-e0d6a9fe4184",
  "name": "Ежемесячная подписка",
  "phoneLast4": "4567",
  "amount": 15000,
  "commentPresent": true,
  "connectionId": "7a67d6bd-5daf-47af-b899-fdb8b7db4d63",
  "schedule": {
    "kind": "monthly", "dayOfMonth": 27, "time": "10:00",
    "shortMonthPolicy": "last_day"
  },
  "timezone": "Asia/Almaty",
  "startsAt": null,
  "endsAt": null,
  "maxOccurrences": null,
  "occurrenceCount": 0,
  "nextRunAt": "2026-09-27T05:00:00.000Z",
  "status": "active",
  "misfirePolicy": "run_once",
  "retryPolicy": { "delays": ["PT6H", "PT1H", "PT15M"] },
  "revision": 1,
  "lastRunAt": null,
  "createdAt": "2026-08-24T10:00:00.000Z",
  "updatedAt": "2026-08-24T10:00:00.000Z",
  "archivedAt": null
}

POST/recurring-invoices/{recurringInvoiceId}/resumeВозобновить правило

Возобновляет расписание по выбранной misfire policy.

Авторизация: Bearer API keyPermission: recurring_invoice:update + invoice:createHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`recurringInvoiceId`	path	`uuid`	Да	Owner-scoped UUID правила автосчёта.
`expectedRevision`	body	`integer >= 1`	Да	Тек текущая revision.

Пример запроса

curl https://api.tolepay.kz/v1/recurring-invoices/$RECURRING_INVOICE_ID/resume \
  -X POST -H "Authorization: Bearer $TOLE_API_KEY" \
  -H "Content-Type: application/json" -d '{"expectedRevision":2}'

200 OK · Пример ответа

{
  "id": "2d229044-8645-4e8b-b3fc-e0d6a9fe4184",
  "name": "Ежемесячная подписка",
  "phoneLast4": "4567",
  "amount": 15000,
  "commentPresent": true,
  "connectionId": "7a67d6bd-5daf-47af-b899-fdb8b7db4d63",
  "schedule": {
    "kind": "monthly", "dayOfMonth": 27, "time": "10:00",
    "shortMonthPolicy": "last_day"
  },
  "timezone": "Asia/Almaty",
  "startsAt": null,
  "endsAt": null,
  "maxOccurrences": null,
  "occurrenceCount": 0,
  "nextRunAt": "2026-09-27T05:00:00.000Z",
  "status": "active",
  "misfirePolicy": "run_once",
  "retryPolicy": { "delays": ["PT6H", "PT1H", "PT15M"] },
  "revision": 1,
  "lastRunAt": null,
  "createdAt": "2026-08-24T10:00:00.000Z",
  "updatedAt": "2026-08-24T10:00:00.000Z",
  "archivedAt": null
}

POST/recurring-invoices/{recurringInvoiceId}/runПоставить внеплановый запуск в очередь

Создаёт durable occurrence и отвечает до обращения в Kaspi. Это выставление счёта сейчас, а не списание денег.

Авторизация: Bearer API keyPermission: recurring_invoice:trigger + invoice:createHTTP: 202 Accepted

Поле	Где	Тип	Обязательно	Описание
`Idempotency-Key`	header	`string`	Да	Уникальный ключ мутации. Повторяйте тот же запрос с тем же ключом.
`recurringInvoiceId`	path	`uuid`	Да	Owner-scoped UUID правила автосчёта.
`expectedRevision`	body	`integer >= 1`	Нет	Необязательный CAS: запуск создаётся только для прочитанной revision правила.

Location указывает на occurrence. До подтверждённого ответа повторяйте тот же run с тем же key: refreshed expectedRevision не меняет semantic request и вернёт исходную occurrence, если первый запрос уже committed.

Пример запроса

curl https://api.tolepay.kz/v1/recurring-invoices/$RECURRING_INVOICE_ID/run \
  -X POST \
  -H "Authorization: Bearer $TOLE_API_KEY" \
  -H "Idempotency-Key: customer-42-run-2026-09-01" \
  -H "Content-Type: application/json" -d '{"expectedRevision":3}'

202 Accepted · Пример ответа

{
  "id": "b83a52dd-4578-44d9-80a0-b0a1b821fd4d",
  "recurringInvoiceId": "2d229044-8645-4e8b-b3fc-e0d6a9fe4184",
  "scheduledFor": "2026-09-27T05:00:00.000Z",
  "status": "pending",
  "attemptCount": 0,
  "nextAttemptAt": null,
  "paymentIntentId": null,
  "commandId": null,
  "lastFailureCode": null,
  "createdAt": "2026-09-27T05:00:00.000Z",
  "updatedAt": "2026-09-27T05:00:00.000Z",
  "completedAt": null
}

DELETE/recurring-invoices/{recurringInvoiceId}?expectedRevision=NАрхивировать правило

Прекращает новые и ожидающие запуски, сохраняя audit, occurrences и платежи. Уже начавшаяся попытка Kaspi не отменяется и может завершиться после архивации.

Авторизация: Bearer API keyPermission: recurring_invoice:deleteHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`recurringInvoiceId`	path	`uuid`	Да	Owner-scoped UUID правила автосчёта.
`expectedRevision`	query	`integer >= 1`	Да	Тек в query; DELETE body не используется.

После архивации проверьте history: уже processing-попытка может завершиться или потребовать сверки в needs_attention.

Пример запроса

curl "https://api.tolepay.kz/v1/recurring-invoices/$RECURRING_INVOICE_ID?expectedRevision=3" \
  -X DELETE -H "Authorization: Bearer $TOLE_API_KEY"

200 OK · Пример ответа

{
  "id": "2d229044-8645-4e8b-b3fc-e0d6a9fe4184",
  "name": "Ежемесячная подписка",
  "phoneLast4": "4567",
  "amount": 15000,
  "commentPresent": true,
  "connectionId": "7a67d6bd-5daf-47af-b899-fdb8b7db4d63",
  "schedule": {
    "kind": "monthly", "dayOfMonth": 27, "time": "10:00",
    "shortMonthPolicy": "last_day"
  },
  "timezone": "Asia/Almaty",
  "startsAt": null,
  "endsAt": null,
  "maxOccurrences": null,
  "occurrenceCount": 0,
  "nextRunAt": "2026-09-27T05:00:00.000Z",
  "status": "active",
  "misfirePolicy": "run_once",
  "retryPolicy": { "delays": ["PT6H", "PT1H", "PT15M"] },
  "revision": 1,
  "lastRunAt": null,
  "createdAt": "2026-08-24T10:00:00.000Z",
  "updatedAt": "2026-08-24T10:00:00.000Z",
  "archivedAt": null
}

GET/recurring-invoices/{recurringInvoiceId}/occurrencesПолучить историю запусков

Возвращает запланированные, выполняющиеся, повторные и завершённые occurrence.

Авторизация: Bearer API keyPermission: recurring_invoice:readHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`recurringInvoiceId`	path	`uuid`	Да	Owner-scoped UUID правила автосчёта.
`cursor`	query	`string`	Нет	Opaque cursor.
`limit`	query	`integer 1..100`	Нет	Размер страницы.
`status`	query	`occurrence status`	Нет	Необязательный фильтр.

Пример запроса

curl "https://api.tolepay.kz/v1/recurring-invoices/$RECURRING_INVOICE_ID/occurrences?limit=20" \
  -H "Authorization: Bearer $TOLE_API_KEY"

200 OK · Пример ответа

{
  "occurrences": [{
  "id": "b83a52dd-4578-44d9-80a0-b0a1b821fd4d",
  "recurringInvoiceId": "2d229044-8645-4e8b-b3fc-e0d6a9fe4184",
  "scheduledFor": "2026-09-27T05:00:00.000Z",
  "status": "pending",
  "attemptCount": 0,
  "nextAttemptAt": null,
  "paymentIntentId": null,
  "commandId": null,
  "lastFailureCode": null,
  "createdAt": "2026-09-27T05:00:00.000Z",
  "updatedAt": "2026-09-27T05:00:00.000Z",
  "completedAt": null
}],
  "nextCursor": null
}

GET/recurring-invoices/{recurringInvoiceId}/occurrences/{occurrenceId}Получить запуск и attempts

Добавляет технические attempts к проекции occurrence для диагностики и reconciliation.

Авторизация: Bearer API keyPermission: recurring_invoice:readHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`recurringInvoiceId`	path	`uuid`	Да	Owner-scoped UUID правила автосчёта.
`occurrenceId`	path	`uuid`	Да	UUID конкретного запланированного запуска.

Пример запроса

curl https://api.tolepay.kz/v1/recurring-invoices/$RECURRING_INVOICE_ID/occurrences/$OCCURRENCE_ID \
  -H "Authorization: Bearer $TOLE_API_KEY"

200 OK · Пример ответа

{
    "id": "b83a52dd-4578-44d9-80a0-b0a1b821fd4d",
  "recurringInvoiceId": "2d229044-8645-4e8b-b3fc-e0d6a9fe4184",
  "scheduledFor": "2026-09-27T05:00:00.000Z",
  "status": "pending",
  "attemptCount": 0,
  "nextAttemptAt": null,
  "paymentIntentId": null,
  "commandId": null,
  "lastFailureCode": null,
  "createdAt": "2026-09-27T05:00:00.000Z",
  "updatedAt": "2026-09-27T05:00:00.000Z",
  "completedAt": null,
  "attempts": [{
    "id":"uuid","attemptNumber":1,"status":"succeeded",
    "scheduledAt":"2026-09-27T05:00:00.000Z","startedAt":"2026-09-27T05:00:01.000Z",
    "completedAt":"2026-09-27T05:00:02.000Z","commandId":"uuid",
    "paymentIntentId":"uuid","failureCode":null
  }]
}

Повторы относятся только к ошибке выставления

retryPolicy.delays выполняется в указанном порядке и не создаёт дубликат уже выставленного, но неоплаченного счёта. При outcome_unknown Tole останавливает правило в needs_attention и не повторяет Kaspi mutation вслепую.

Rule statuses: active, paused, completed, needs_attention, archived. Occurrence statuses: pending, processing, retry_scheduled, succeeded, failed, needs_attention, skipped. misfirePolicy=run_once создаёт не более одной occurrence после простоя, а skip фиксирует пропуски без catch-up.

Автосчета сейчас работают только с live Kaspi connection. Не добавляйте /sandbox к этим маршрутам, пока такой mirror явно не появится в OpenAPI.

JWT mirror кабинета: /v1/automations/recurring-invoices с теми же суффиксами. Dashboard может передать connectionId в body create; если поле опущено, сервер резолвит и сохраняет текущее основное подключение. Внутренний ключ получает точные recurring permissions и invoice:create.

Sandbox API

Sandbox работает на том же production Base URL, повторяет основной контракт, хранит команды и payment intents в базе, создаёт события и webhooks, но никогда не обращается в Kaspi.

Зеркальные sandbox-маршруты

Для всех строк ниже добавьте /sandbox перед live path. Схемы запросов и control-ответы мутаций совпадают с live; data содержит синтетические sandbox-значения. X-Tole-Connection-Id обязателен.

POST/sandbox/invoices/client-info

invoice:read

POST/sandbox/invoices

invoice:create

GET/sandbox/invoices/history

invoice:read

GET/sandbox/invoices/{operationId}

invoice:read

POST/sandbox/invoices/{operationId}/cancel

invoice:cancel

POST/sandbox/qr

qr:create

GET/sandbox/qr/{operationId}

qr:read

GET/sandbox/history/operations

history:read

GET/sandbox/history/operations/{operationId}

history:read

POST/sandbox/refunds

refund:create

GET/sandbox/commands/{commandId}

permission исходной команды

201 Created · sandbox invoice

{
  "ok": true,
  "data": {
    "id": "uuid", "kind": "invoice", "status": "created", "amount": 5000,
    "clientPhoneLast4": "4567", "orderNumber": "SBX-1234ABCD", "environment": "sandbox"
  },
  "commandId": "uuid", "replayed": false
}

201 Created · sandbox QR

{
  "ok": true,
  "data": {
    "id": "uuid", "kind": "qr", "status": "created", "amount": 5000,
    "paymentUrl": "https://sandbox.tole.test/pay/uuid",
    "qrToken": "https://sandbox.tole.test/qr/uuid", "environment": "sandbox"
  },
  "commandId": "uuid", "replayed": false
}

POST/sandbox/connectionsСоздать sandbox-подключение

Management endpoint с пользовательским JWT, а не API key.

Авторизация: Bearer JWTHTTP: 201 Created

Поле	Где	Тип	Обязательно	Описание
`displayName`	body	`string`	Да	Название 1–100 символов.

Пример запроса

curl https://api.tolepay.kz/v1/sandbox/connections \
  -X POST -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"displayName":"Development"}'

201 Created · Пример ответа

{
  "id": "uuid", "providerMode": "sandbox", "status": "active", "displayName": "Development"
}

GET/sandbox/payment-intents/{paymentIntentId}Получить sandbox payment intent

Durable test-состояние счёта или QR.

Авторизация: Bearer API keyPermission: history:readHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`X-Tole-Connection-Id`	header	`string`	Да	Обязательный UUID sandbox-подключения.
`paymentIntentId`	path	`uuid`	Да	UUID платёжного намерения Tole.

Пример запроса

curl https://api.tolepay.kz/v1/sandbox/payment-intents/$PAYMENT_INTENT_ID \
  -H "Authorization: Bearer $TOLE_TEST_API_KEY" \
  -H "X-Tole-Connection-Id: $SANDBOX_CONNECTION_ID"

200 OK · Пример ответа

{
  "ok": true,
  "data": { "id": "uuid", "kind": "invoice", "status": "pending", "amount": 5000, "currency": "KZT", "environment": "sandbox" }
}

POST/sandbox/payment-intents/{paymentIntentId}/simulateСмоделировать результат оплаты

Переводит sandbox intent в terminal status и создаёт webhook-событие.

Авторизация: Bearer API keyPermission: sandbox:simulateHTTP: 200 OK

Поле	Где	Тип	Обязательно	Описание
`X-Tole-Connection-Id`	header	`string`	Да	Обязательный UUID sandbox-подключения.
`paymentIntentId`	path	`uuid`	Да	UUID платёжного намерения Tole.
`status`	body	`enum`	Да	paid \| cancelled \| expired \| failed

Пример запроса

curl https://api.tolepay.kz/v1/sandbox/payment-intents/$PAYMENT_INTENT_ID/simulate \
  -X POST \
  -H "Authorization: Bearer $TOLE_TEST_API_KEY" \
  -H "X-Tole-Connection-Id: $SANDBOX_CONNECTION_ID" \
  -H "Content-Type: application/json" \
  -d '{"status":"paid"}'

200 OK · Пример ответа

{
  "ok": true,
  "data": { "id": "uuid", "kind": "invoice", "status": "paid", "environment": "sandbox" }
}

API-ключи и permissions

Ключ создаётся в кабинете или через management API с пользовательским JWT. Raw secret возвращается только при создании; дальше API показывает только безопасный prefix.

GET/api-keys

JWT · Список ключей; query cursor и limit 1–100

POST/api-keys

JWT · Создать: { name, grants: [{ connectionId, permissions }] }

PUT/api-keys/{apiKeyId}

JWT · Заменить name и grants; нужен expectedRevision

POST/api-keys/{apiKeyId}/revoke

JWT · Отозвать ключ; повторный revoke безопасен

Permission	Разрешает
`invoice:create`	POST /invoices; также execution binding для recurring create/update/resume/run
`invoice:read`	client-info, invoice history/details, invoice payment intent
`invoice:cancel`	POST /invoices/{id}/cancel
`qr:create`	POST /qr
`qr:read`	QR details и QR payment intent
`history:read`	history endpoints и sandbox payment intent
`refund:create`	POST /refunds
`recurring_invoice:create`	POST /recurring-invoices; дополнительно требуется invoice:create
`recurring_invoice:read`	список, detail и occurrences автосчетов
`recurring_invoice:update`	PATCH, pause и resume; PATCH/resume дополнительно требуют invoice:create
`recurring_invoice:delete`	DELETE-архивирование автосчёта
`recurring_invoice:trigger`	POST /recurring-invoices/{id}/run; дополнительно требуется invoice:create
`sandbox:simulate`	POST /sandbox/payment-intents/{id}/simulate

POST /api-keys · request

{
  "name": "Production backend",
  "grants": [{
    "connectionId": "7a67d6bd-5daf-47af-b899-fdb8b7db4d63",
    "permissions": ["invoice:create", "invoice:read", "invoice:cancel"]
  }]
}

201 Created · secret returned once

{
  "apiKey": {
    "id": "uuid", "name": "Production backend", "keyPrefix": "tole_sk_live_v1.…", "status": "active",
    "revision": 1,
    "grants": [{
      "connectionId": "uuid", "connectionName": "main", "environment": "live",
      "permissions": ["invoice:create", "invoice:read", "invoice:cancel"]
    }]
  },
  "secret": "tole_sk_live_v1.<uuid>.<secret>"
}

Webhooks

Webhook endpoints и deliveries доступны с пользовательским JWT или любым активным tole_sk_* этого владельца; grants подключения не требуются. URL должен быть HTTPS. Signing secret whsec_* возвращается один раз.

GET/webhook-endpoints

JWT / tole_sk_* · Список endpoint-ов

POST/webhook-endpoints

JWT / tole_sk_* · Создать: { name, url }; secret возвращается один раз

POST/webhook-endpoints/{endpointId}/disable

JWT / tole_sk_* · Отключить; body {}

GET/webhook-deliveries?status=…

JWT / tole_sk_* · pending | processing | delivered | dead_letter

POST/webhook-deliveries/{deliveryId}/replay

JWT / tole_sk_* · Повторить dead-letter delivery; body {}

HTTP delivery

`webhook-id`

UUID события

`webhook-timestamp`

Unix timestamp

`webhook-signature`

v1=<hex HMAC-SHA256>

Payment webhook event

{
  "id": "c2e94dd8-9802-44e7-a52b-14f45d5b9cdb",
  "type": "payment.paid",
  "createdAt": "2026-08-23T10:01:00.000Z",
  "data": { "paymentIntentId": "33ec20dc-8d82-4077-a557-d59328853df9", "connectionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "providerStatus": "Processed", "receiptUrl": "https://example.test/receipt/123", "receiptStatus": "available" }
}

Чеки платежей

Новый payment.paid содержит paymentIntentId, connectionId, receiptUrl и receiptStatus. Если Kaspi ещё не предоставил чек, receiptUrl равен null, receiptStatus — unavailable; это не отменяет успешную оплату. Позднее запросите чек через GET /invoices/{id}/receipt или GET /payment-intents/invoices/{paymentIntentId}/receipt. Для QR замените invoices на qr. Требуется invoice:read или qr:read. Внешняя ссылка возвращается сразу. Защищённый чек загружается сервером: receiptDocument (title, amount, currency, merchant, fields), receiptUrl: null, receiptStatus: available. Старые webhook не переписываются.

Integrator API: GET /integrator/customers/{externalCustomerId}/connections/{connectionId}/invoices/{resourceId}/receipt (scope invoices:read); для QR — /qr/{resourceId}/receipt (qr:read). Tole возвращает ссылку провайдера, не формирует фискальный чек ОФД. Открытие, сохранение и печать зависят от страницы Kaspi.

Payment event types: payment.created, payment.paid, payment.cancelled, payment.expired, payment.failed, payment.partially_refunded, payment.refunded, refund.reserved, refund.succeeded, refund.rejected, refund.outcome_unknown, operation.succeeded, operation.rejected, operation.outcome_unknown.

Recurring-invoice lifecycle event

{
  "id": "07dc5b90-f306-4f73-9d7e-6079f809825a",
  "type": "recurring_invoice.occurrence.succeeded",
  "createdAt": "2026-09-27T05:00:02.000Z",
  "data": {
    "recurringInvoiceId": "2d229044-8645-4e8b-b3fc-e0d6a9fe4184",
    "occurrenceId": "b83a52dd-4578-44d9-80a0-b0a1b821fd4d",
    "attemptNumber": 1,
    "scheduledFor": "2026-09-27T05:00:00.000Z",
    "status": "succeeded",
    "paymentIntentId": "33ec20dc-8d82-4077-a557-d59328853df9",
    "commandId": "a7a5d4dc-c623-456c-b176-8ec1f1000dc1"
  }
}

Recurring lifecycle: recurring_invoice.created, updated, paused, resumed, completed, needs_attention, archived; occurrence events: created, retry_scheduled, succeeded, failed, needs_attention, skipped. Обычные payment events созданного счёта дополнительно несут source: scheduled_invoice, recurringInvoiceId, occurrenceId и attemptNumber.

Новые payment.paid содержат paymentIntentId. Старые события могут не содержать его; итоговое состояние можно сверить по сохранённым UUID через payment-intent endpoints.

Проверяйте подпись по exact raw body до JSON.parse. Сохраняйте event id и обрабатывайте событие идемпотентно. Возвращайте 2xx только после надёжной фиксации события.

Node.js · signature verification

import { createHmac, timingSafeEqual } from "node:crypto";

const signed = `${webhookId}.${timestamp}.${rawBody}`;
const expected = "v1=" + createHmac("sha256", secret)
  .update(signed, "utf8")
  .digest("hex");

const actualBytes = Buffer.from(signature, "utf8");
const expectedBytes = Buffer.from(expected, "utf8");
if (actualBytes.length !== expectedBytes.length ||
    !timingSafeEqual(actualBytes, expectedBytes)) {
  throw new Error("Invalid Tole webhook signature");
}

Billing management API

Эти endpoints обслуживают тариф, usage и оплату подписки в кабинете. Они используют пользовательский JWT, а не публичный API key.

GET/billing/overview

JWT · Subscription, usage, invoices и текущий checkout

GET/billing/plans

JWT · Доступные публичные планы и entitlements

GET/billing/invoices/{invoiceId}

JWT · Получить owner-scoped billing invoice

POST/billing/checkout

JWT · Создать или продолжить checkout: { planCode }

GET/billing/checkout/{checkoutId}

JWT · Получить статус checkout

POST/billing/subscription/cancel

JWT · Отменить подписку в конце периода

POST/billing/webhooks/kaspi

provider callback · Служебный HMAC callback; не вызывается merchant-интеграцией

POST /billing/checkout · request

{
  "planCode": "business"
}

201 Created · checkout

{
  "id": "uuid",
  "status": "pending",
  "planCode": "business",
  "planName": "Business",
  "amountKzt": 22500,
  "currency": "KZT",
  "paymentUrl": "https://…",
  "receiptUrl": null,
  "expiresAt": "2026-08-23T11:00:00.000Z",
  "paidAt": null,
  "createdAt": "2026-08-23T10:00:00.000Z"
}

Форматы ответов, идемпотентность и polling

200 / 201

Complete

Сохраните data.id/paymentIntentId и commandId. Повтор с тем же Idempotency-Key вернёт тот же результат и header Idempotent-Replayed: true.

202 in_progress

Wait

Читайте Retry-After: 2 и Location. Poll GET /commands/:commandId. Не создавайте новую mutation.

202 outcome_unknown

Do not retry

Kaspi мог выполнить операцию. Проверяйте command и payment intent; новый create может дать дубль.

202 Accepted · in progress

{
  "ok": false, "kind": "in_progress", "commandId": "uuid", "replayed": true
}

202 Accepted · outcome unknown

{
  "ok": false, "kind": "outcome_unknown", "commandId": "uuid", "replayed": false
}

Payment intent statuses: pending, paid, cancelled, expired, failed, partially_refunded, refunded.

Ошибки REST API

В коде интеграции ветвитесь по HTTP status и code. message предназначен только для диагностики и может измениться.

Error response

{
  "statusCode": 409,
  "code": "PUBLIC_API_IDEMPOTENCY_CONFLICT",
  "message": "The Idempotency-Key was already used for a different request"
}

HTTP	code	Что делать
400	`PUBLIC_API_VALIDATION_ERROR`	Исправить body, query, UUID или заголовок. Не повторять без изменения запроса.
401	`API_KEY_INVALID_CREDENTIAL`	Проверить namespace и заменить неверный или отозванный ключ.
402	`BILLING_SUBSCRIPTION_UNAVAILABLE` `BILLING_ENTITLEMENT_UNAVAILABLE`	Активировать тариф или возможность.
403	`PUBLIC_API_FORBIDDEN`	Проверить grant, permission и X-Tole-Connection-Id.
404	`PUBLIC_API_RESOURCE_NOT_FOUND`	Проверить локальный UUID и environment; чужие ресурсы также выглядят как 404.
409	`PUBLIC_API_IDEMPOTENCY_CONFLICT`	Не менять body под старым ключом. Для новой операции создать новый key.
409	`PUBLIC_API_DEFAULT_CONNECTION_REQUIRED` `PUBLIC_API_DEFAULT_CONNECTION_UNAVAILABLE`	Передать connection header или исправить основное подключение.
409	`PAYMENT_INVALID_STATE` `PAYMENT_REFUND_LIMIT_EXCEEDED`	Перечитать payment intent и исправить переход или сумму.
400	`RECURRING_INVOICE_VALIDATION_ERROR`	Исправить расписание, timezone, окно, retry delays или лимиты полей.
404	`RECURRING_INVOICE_NOT_FOUND` `RECURRING_INVOICE_OCCURRENCE_NOT_FOUND`	Проверить owner-scoped UUID; чужой ресурс также выглядит как 404.
409	`RECURRING_INVOICE_CONCURRENT_MODIFICATION` `RECURRING_INVOICE_INVALID_STATE` `RECURRING_INVOICE_IDEMPOTENCY_CONFLICT`	Перечитать revision/status; не менять semantic request под прежним idempotency key.
409	`RECURRING_INVOICE_DEFAULT_CONNECTION_REQUIRED` `RECURRING_INVOICE_CONNECTION_UNAVAILABLE`	Выбрать готовое live-подключение с нужными permissions.
503	`RECURRING_INVOICE_UNAVAILABLE`	Для read/preview применить backoff; после mutation сначала перечитать правило или occurrence.
429	`RATE_LIMIT_EXCEEDED` `BILLING_LIMIT_EXCEEDED`	Соблюдать Retry-After или лимит тарифа.
502	`PUBLIC_API_UPSTREAM_REJECTED`	Kaspi отклонил команду. Исправить бизнес-условия перед новой командой.
503	`PUBLIC_API_UNAVAILABLE` `RATE_LIMIT_UNAVAILABLE`	Для read — backoff. Для mutation сначала проверить commandId.
500	`PUBLIC_API_INTERNAL_ERROR`	Сохранить безопасный context и обратиться в поддержку.