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

Жылдам бастау

Base URL: https://api.tolepay.kz/v1. Алғашқы интеграция үшін Kaspi-ге сұрау жібермейтін test кілт пен /sandbox пайдаланыңыз.

Sandbox қосылымын жасаңыз

Кабинетте «API кілттері» → «Тест кілтін жасау» таңдаңыз. Қосылым автоматты дайындалады, Kaspi және ақылы жазылым қажет емес.

Test API кілтін жасаңыз

Құқықтар жиынын таңдаңыз. Кілтті, қосылым ID-ін және дайын сұрауларды сақтаңыз. JWT қажет емес; GET /api-key құқықтар мен қосылымдарды көрсетеді.

Шот немесе QR жасаңыз

Bearer кілтін, X-Tole-Connection-Id және бірегей Idempotency-Key жіберіңіз.

Төлемді модельдеңіз

paid мәртебесімен simulate шақырып, webhook өңдегішін тексеріңіз.

Live-қа ауысыңыз

Test кілт пен /sandbox маршруттарын live нұсқасына ауыстырыңыз. Test ID live-қа көшірілмейді.

Kaspi кассирін дайындау

Авторизация және ортақ тақырыптар

Төлем endpoint-терін тек backend-тен шақырыңыз. tole_sk_* мәнін браузерге, мобильді қолданбаға немесе frontend логтарына жібермеңіз.

`Authorization`

Міндетті. Live үшін Bearer tole_sk_live_v1…, sandbox үшін Bearer tole_sk_test_v1….

`Content-Type`

Body бар сұраулар үшін application/json.

`X-Tole-Connection-Id`

Қосылым UUID-і. Негізгі қосылым бар live режимінде міндетті емес; sandbox-та әрқашан міндетті.

`Idempotency-Key`

Create/cancel/refund үшін міндетті. Бір бизнес сұрау — бір кілт.

Кілт құқықтары таңдалған қосылым үшін тексеріледі. Басқа қосылымға 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 — Tole жергілікті UUID-лері.

POST/invoices/client-infoШот алушысын тексеру

Kaspi көрсетілген нөмірге шот жібере алатынын тексереді. Клиент аты мен толық телефоны қайтарылмайды.

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

Өріс	Орны	Түрі	Міндетті	Сипаттама
`X-Tole-Connection-Id`	header	`string`	Жоқ	Live қосылым UUID-і; негізгі қосылым болса міндетті емес.
`phoneNumber`	body	`string`	Иә	Қазақстан нөмірі: +7 және 10 сан.

Safe өрістер Kaspi жауабына байланысты.

Сұрау үлгісі

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 — келесі сұрауларға арналған Tole UUID-і.

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

Өріс	Орны	Түрі	Міндетті	Сипаттама
`X-Tole-Connection-Id`	header	`string`	Жоқ	Live қосылым UUID-і; негізгі қосылым болса міндетті емес.
`Idempotency-Key`	header	`string`	Иә	Mutation үшін бірегей кілт. Сол сұрауды сол кілтпен қайталаңыз.
`phoneNumber`	body	`string`	Иә	+7 және 10 сан.
`amount`	body	`integer`	Иә	KZT сомасы: 1–100 000 000.
`comment`	body	`string`	Жоқ	Міндетті емес, 200 таңбаға дейін.

receiptUrl және orderNumber міндетті емес.

Сұрау үлгісі

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`	Жоқ	Live қосылым UUID-і; негізгі қосылым болса міндетті емес.

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}Шот деректерін алу

Provider-ден ағымдағы деректерді оқиды.

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

Өріс	Орны	Түрі	Міндетті	Сипаттама
`X-Tole-Connection-Id`	header	`string`	Жоқ	Live қосылым UUID-і; негізгі қосылым болса міндетті емес.
`operationId`	path	`uuid`	Иә	Tole операциясының жергілікті UUID-і.

Сұрау үлгісі

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`	Жоқ	Live қосылым UUID-і; негізгі қосылым болса міндетті емес.
`Idempotency-Key`	header	`string`	Иә	Mutation үшін бірегей кілт. Сол сұрауды сол кілтпен қайталаңыз.
`operationId`	path	`uuid`	Иә	Tole операциясының жергілікті UUID-і.

Сұрау үлгісі

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`	Жоқ	Live қосылым UUID-і; негізгі қосылым болса міндетті емес.
`Idempotency-Key`	header	`string`	Иә	Mutation үшін бірегей кілт. Сол сұрауды сол кілтпен қайталаңыз.
`amount`	body	`integer`	Иә	KZT сомасы: 1–100 000 000.
`latitude`	body	`number`	Жоқ	Міндетті емес, −90…90; longitude бірге.
`longitude`	body	`number`	Жоқ	Міндетті емес, −180…180; latitude бірге.

expiresAt және receiptUrl міндетті емес.

Сұрау үлгісі

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 деректерін алу

Provider-ден QR мәртебесін оқиды.

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

Өріс	Орны	Түрі	Міндетті	Сипаттама
`X-Tole-Connection-Id`	header	`string`	Жоқ	Live қосылым UUID-і; негізгі қосылым болса міндетті емес.
`operationId`	path	`uuid`	Иә	Tole операциясының жергілікті UUID-і.

Сұрау үлгісі

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 күніне дейінгі операциялар тарихы.

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

Өріс	Орны	Түрі	Міндетті	Сипаттама
`X-Tole-Connection-Id`	header	`string`	Жоқ	Live қосылым UUID-і; негізгі қосылым болса міндетті емес.
`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`	Жоқ	Live қосылым UUID-і; негізгі қосылым болса міндетті емес.
`operationId`	path	`uuid`	Иә	Tole операциясының жергілікті UUID-і.
`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`	Жоқ	Live қосылым UUID-і; негізгі қосылым болса міндетті емес.
`Idempotency-Key`	header	`string`	Иә	Mutation үшін бірегей кілт. Сол сұрауды сол кілтпен қайталаңыз.
`operationId`	body	`uuid`	Иә	Invoice/QR payment intent жергілікті UUID-і.
`returnAmount`	body	`integer`	Иә	KZT, қолжетімді қалдықтан аспайды.

Сұрау үлгісі

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}Шоттың сақталған мәртебесін алу

Tole ledger ішіндегі күйді оқиды.

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

Өріс	Орны	Түрі	Міндетті	Сипаттама
`X-Tole-Connection-Id`	header	`string`	Жоқ	Live қосылым UUID-і; негізгі қосылым болса міндетті емес.
`paymentIntentId`	path	`uuid`	Иә	Tole төлем ниетінің UUID-і.

Сұрау үлгісі

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 сақталған мәртебесін алу

QR үшін durable payment-intent келісімшарты.

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

Өріс	Орны	Түрі	Міндетті	Сипаттама
`X-Tole-Connection-Id`	header	`string`	Жоқ	Live қосылым UUID-і; негізгі қосылым болса міндетті емес.
`paymentIntentId`	path	`uuid`	Иә	Tole төлем ниетінің UUID-і.

Сұрау үлгісі

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}Идемпотентті команданы тексеру

202 не желі қатесінен кейін command нәтижесін тексереді.

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

Өріс	Орны	Түрі	Міндетті	Сипаттама
`commandId`	path	`uuid`	Иә	commandId не Location ішіндегі UUID.

Команда connection мен permission мәнін өзі анықтайды.

Сұрау үлгісі

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"
  }
}

Автошоттар

Автошот typed кесте бойынша әдеттегі Kaspi қашықтан шотын автоматты шығарады. Бұл автотөлем емес: сатып алушы төлеуді өзі шешеді.

Ереже нақты 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 YYYY-MM-DD форматындағы тұрақты жергілікті anchorDate қайтарады; N апта сайынғы cadence өзгерткенде оны сақтаңыз. 29–31 күндер үшін last_day іске қосуды қысқа айдың соңғы күніне ауыстырады, ал skip сол айды өткізіп жібереді. anchorAt және runAt қатаң YYYY-MM-DDTHH:mm форматында, секундсыз және offset-сіз беріледі.

POST/recurring-invoices/previewКестені алдын ала қарау

Ережені сақтамай және Kaspi-ге жүгінбей келесі 1–20 UTC уақытын есептейді.

Авторизация: 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`	Жоқ	Live қосылым UUID-і; негізгі қосылым болса міндетті емес.
`Idempotency-Key`	header	`string`	Иә	Mutation үшін бірегей кілт. Сол сұрауды сол кілтпен қайталаңыз.
`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`	Иә	Кестенің wall-clock өрістеріне арналған timezone.
`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.

Header жоқ болса, сервер 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Ережелер тізімін алу

Кілтте read grant бар барлық connections ережелерін қайтарады. Status жоқ болса, мұрағат кірмейді.

Авторизация: 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`	Иә	Соңғы GET ішіндегі revision; өзгерістердің жоғалуынан қорғайды.
`изменяемые поля`	body	`partial create body`	Жоқ	expectedRevision-нан басқа кемінде бір өріс. null тиісті баптауды тазартады.

Ескірген revision 409 қайтарады: ережені қайта оқып, шешімді жаңа нұсқада қолданыңыз.

Сұрау үлгісі

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`	Иә	Mutation үшін бірегей кілт. Сол сұрауды сол кілтпен қайталаңыз.
`recurringInvoiceId`	path	`uuid`	Иә	Автошот ережесінің owner-scoped UUID-і.
`expectedRevision`	body	`integer >= 1`	Жоқ	Міндетті емес CAS: іске қосу тек оқылған rule revision үшін жасалады.

Location occurrence-қа сілтейді. Расталған жауапқа дейін сол run үшін сол key қолданыңыз: жаңартылған expectedRevision semantic request-ті өзгертпейді және алғашқы сұрау committed болса, бастапқы occurrence қайтарылады.

Сұрау үлгісі

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 алу

Диагностика және reconciliation үшін occurrence-қа техникалық attempts қосады.

Авторизация: 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 үшін жұмыс істейді. OpenAPI-де mirror пайда болмайынша бұл маршруттарға /sandbox қоспаңыз.

Кабинеттің JWT mirror маршруты: /v1/automations/recurring-invoices, суффикстері бірдей. Dashboard create body ішінде connectionId жібере алады; өріс болмаса, сервер ағымдағы негізгі қосылымды таңдап сақтайды. Ішкі кілт нақты recurring permissions және invoice:create алады.

Sandbox API

Sandbox сол production Base URL-де жұмыс істейді, негізгі келісімшартты қайталайды, командалар мен webhooks жасайды, бірақ Kaspi-ге сұрау жібермейді.

Sandbox айна маршруттары

Live path алдына /sandbox қосыңыз. Сұрау схемалары бірдей, 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/connectionsSandbox қосылымын жасау

API key емес, пайдаланушы JWT қолданады.

Авторизация: 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 алу

Шот не QR test күйі.

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

Өріс	Орны	Түрі	Міндетті	Сипаттама
`X-Tole-Connection-Id`	header	`string`	Иә	Sandbox қосылымының міндетті UUID-і.
`paymentIntentId`	path	`uuid`	Иә	Tole төлем ниетінің UUID-і.

Сұрау үлгісі

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`	Иә	Sandbox қосылымының міндетті UUID-і.
`paymentIntentId`	path	`uuid`	Иә	Tole төлем ниетінің UUID-і.
`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

Кілт кабинетте немесе JWT арқылы management API-мен жасалады. Raw secret тек бір рет қайтарылады.

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_* кілті арқылы қолжетімді; connection grant қажет емес. URL HTTPS болуы тиіс. 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.

Integrator API: GET /integrator/customers/{externalCustomerId}/connections/{connectionId}/invoices/{resourceId}/receipt; QR: /qr/{resourceId}/receipt. Tole провайдер сілтемесін қайтарады, фискалдық чек жасамайды.

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

Тариф, usage және жазылым төлеміне арналған JWT endpoints.

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 и обратиться в поддержку.