### POST /recurring-invoices/{recurringInvoiceId}/run - Example response

Source: https://tolepay.kz/ru/docs

Example JSON response for the run endpoint, showing a pending occurrence with scheduledFor, status, and attemptCount.

```json
{
  "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
}
```

--------------------------------

### Schedule without cron - Example response

Source: https://tolepay.kz/ru/docs

Example 200 OK response for a recurring invoice with a monthly schedule. Shows the schedule object with kind, dayOfMonth, time, and shortMonthPolicy, plus timezone, retryPolicy, and status fields.

```json
{
  "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 /billing/overview

Source: https://tolepay.kz/ru/docs

Retrieves subscription, usage, invoices, and current checkout information for the authenticated user.

```APIDOC
## GET /billing/overview

### Description
Retrieves subscription, usage, invoices, and current checkout information for the authenticated user.

### Method
GET

### Endpoint
/billing/overview

### Authentication
JWT
```

--------------------------------

### Get QR Details GET /qr/{operationId}

Source: https://tolepay.kz/ru/docs

Retrieves the current status of a QR operation by its UUID.

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

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

--------------------------------

### POST /api-keys request

Source: https://tolepay.kz/ru/docs

Example request body for creating an API key with grants for specific permissions.

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

--------------------------------

### Payment webhook event payload example

Source: https://tolepay.kz/ru/docs

Example JSON payload for a payment.paid webhook event. Contains id, type, createdAt, and data with providerStatus and environment fields.

```json
{
  "id": "c2e94dd8-9802-44e7-a52b-14f45d5b9cdb",
  "type": "payment.paid",
  "createdAt": "2026-08-23T10:01:00.000Z",
  "data": { "providerStatus": "SandboxProcessed", "environment": "sandbox" }
}
```

--------------------------------

### GET /billing/plans

Source: https://tolepay.kz/ru/docs

Retrieves available public plans and their entitlements.

```APIDOC
## GET /billing/plans

### Description
Retrieves available public plans and their entitlements.

### Method
GET

### Endpoint
/billing/plans

### Authentication
JWT
```

--------------------------------

### Error Response JSON Example

Source: https://tolepay.kz/ru/docs

Example of an error response body with statusCode, code, and message fields. The message is for diagnostics only and may change.

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

--------------------------------

### Get QR Status Request

Source: https://tolepay.kz/ru/docs

Retrieves the status of a QR payment intent.

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

--------------------------------

### 201 Created · sandbox QR response

Source: https://tolepay.kz/ru/docs

Example JSON response for a successfully created sandbox QR code.

```json
{
  "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
}
```

--------------------------------

### 201 Created response with secret

Source: https://tolepay.kz/ru/docs

Example response after creating an API key, including the apiKey object and the secret returned only once.

```json
{
  "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>"
}
```

--------------------------------

### 201 Created · sandbox invoice response

Source: https://tolepay.kz/ru/docs

Example JSON response for a successfully created sandbox invoice.

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

--------------------------------

### Get History Operation Details GET /history/operations/{operationId}

Source: https://tolepay.kz/ru/docs

Retrieves secure details for a specific operation using its UUID.

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

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

--------------------------------

### Get QR Status Response

Source: https://tolepay.kz/ru/docs

Successful response containing the QR payment intent details.

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

--------------------------------

### GET /qr/{operationId}

Source: https://tolepay.kz/ru/docs

Reads the current status of a QR from the provider. Requires the qr:read permission.

```APIDOC
## GET /qr/{operationId}

### Description
Reads the current status of a QR from the provider.

### Method
GET

### Endpoint
https://api.tolepay.kz/v1/qr/{operationId}

### Parameters
#### Headers
- **X-Tole-Connection-Id** (string) - Optional - UUID live-connection; can be omitted if main connection is configured.

#### Path Parameters
- **operationId** (uuid) - Required - Local owner-scoped UUID of the Tole operation.

### Request Example
```curl https://api.tolepay.kz/v1/qr/$OPERATION_ID \ n  -H "Authorization: Bearer $TOLE_API_KEY" n``` n
### Response
#### Success Response (200 OK)
- **ok** (boolean) - Indicates success.
- **data** (object) - Contains QR details.
  - **amount** (integer) - Amount in KZT.
  - **currency** (string) - Currency code (e.g., KZT). n  - **status** (string) - Status of the QR.

#### Response Example
```json
{
  "ok": true,
  "data": { "amount": 5000, "currency": "KZT", "status": "Processed" }
}
```
```

--------------------------------

### GET /billing/checkout/{checkoutId}

Source: https://tolepay.kz/ru/docs

Retrieves the status of a checkout session by its ID.

```APIDOC
## GET /billing/checkout/{checkoutId}

### Description
Retrieves the status of a checkout session by its ID.

### Method
GET

### Endpoint
/billing/checkout/{checkoutId}

### Authentication
JWT

### Parameters
#### Path Parameters
- **checkoutId** (string) - Required - The ID of the checkout session.
```

--------------------------------

### GET /sandbox/payment-intents/{paymentIntentId}

Source: https://tolepay.kz/ru/docs

Retrieves a sandbox payment intent, which represents the durable test state of an invoice or QR.

```APIDOC
## GET /sandbox/payment-intents/{paymentIntentId}

### Description
Retrieves a sandbox payment intent, which represents the durable test state of an invoice or QR.

### Method
GET

### Endpoint
/sandbox/payment-intents/{paymentIntentId}

### Authentication
Bearer API key

### Permission
history:read

### Parameters
#### Path Parameters
- **paymentIntentId** (uuid) - Required - UUID of the Tole payment intent.

#### Headers
- **X-Tole-Connection-Id** (string) - Required - UUID of the sandbox connection.

### Request Example
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"

### Response
#### Success Response (200 OK)
Sandbox payment intent object.

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

```

--------------------------------

### Get invoice history

Source: https://tolepay.kz/ru/docs

Retrieves a secure history of invoices for the selected connection.

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

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

--------------------------------

### Get invoice details

Source: https://tolepay.kz/ru/docs

Fetches current invoice details from the provider and updates the payment intent status.

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

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

--------------------------------

### GET /api-keys

Source: https://tolepay.kz/ru/docs

Lists all API keys. Requires JWT authentication. Supports cursor-based pagination with a limit between 1 and 100.

```APIDOC
## GET /api-keys

### Description
Lists all API keys. Requires JWT authentication. Supports cursor-based pagination with a limit between 1 and 100.

### Method
GET

### Endpoint
/api-keys

### Parameters
#### Query Parameters
- **cursor** (string) - Optional - Pagination cursor
- **limit** (integer) - Optional - Number of items per page, between 1 and 100

### Authentication
JWT
```

--------------------------------

### GET /webhook-endpoints

Source: https://tolepay.kz/ru/docs

Lists all webhook endpoints for the authenticated owner. Requires JWT or an active tole_sk_* secret.

```APIDOC
## GET /webhook-endpoints

### Description
Lists all webhook endpoints for the authenticated owner.

### Method
GET

### Endpoint
/webhook-endpoints

### Authentication
JWT or tole_sk_* secret

### Response
#### Success Response (200)
- **endpoints** (array) - List of webhook endpoints

#### Response Example
{
  "endpoints": []
}
```

--------------------------------

### Webhook Signature Verification (Node.js)

Source: https://tolepay.kz/ru/docs

Example code for verifying the webhook signature using HMAC-SHA256 and timing-safe comparison.

```APIDOC
## Webhook Signature Verification (Node.js)

### Description
Verifies the webhook signature using the raw body and the signing secret.

### Code
```javascript
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");
}
```
```

--------------------------------

### GET /recurring-invoices

Source: https://tolepay.kz/ru/docs

Lists all recurring invoice rules for all accessible connections. Requires the recurring_invoice:read scope.

```APIDOC
## GET /recurring-invoices

### Description
Lists all recurring invoice rules for all accessible connections. Requires the recurring_invoice:read scope.

### Method
GET

### Endpoint
/recurring-invoices

### Parameters
No parameters.

### Request Example
```
curl https://api.tolepay.kz/v1/recurring-invoices \
  -H "Authorization: Bearer $TOLE_API_KEY"
```

### Response
#### Success Response (200)
- **recurringInvoices** (array) - List of recurring invoice rules.

#### Response Example
```
{
  "recurringInvoices": [
    {
      "recurringInvoiceId": "ri_123",
      "phoneLast4": "1234",
      "commentPresent": true
    }
  ]
}
```
```

--------------------------------

### Example Response for Recurring Invoice Occurrences

Source: https://tolepay.kz/ru/docs

A sample JSON response showing a list of occurrences for a recurring invoice.

```json
{
  "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 /sandbox/payment-intents/{paymentIntentId} request and response

Source: https://tolepay.kz/ru/docs

Retrieve the status of a sandbox payment intent. Requires the X-Tole-Connection-Id header and a valid API key.

```bash
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"
```

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

--------------------------------

### GET /sandbox/qr/{operationId}

Source: https://tolepay.kz/ru/docs

Sandbox endpoint to retrieve a specific QR code by operation ID. Mirrors the live endpoint but returns synthetic sandbox data.

```APIDOC
## GET /sandbox/qr/{operationId}

### Description
Sandbox endpoint to retrieve a specific QR code by operation ID. Mirrors the live endpoint but returns synthetic sandbox data.

### Method
GET

### Endpoint
/sandbox/qr/{operationId}

### Parameters
#### Path Parameters
- **operationId** (string) - Required - The operation ID of the QR code.

#### Headers
- **X-Tole-Connection-Id** (string) - Required - UUID of the sandbox connection.

### Permission
qr:read

### Response
#### Success Response (200)
Synthetic sandbox data.

```

--------------------------------

### GET /sandbox/commands/{commandId}

Source: https://tolepay.kz/ru/docs

Sandbox endpoint to retrieve a command by ID. Mirrors the live endpoint but returns synthetic sandbox data.

```APIDOC
## GET /sandbox/commands/{commandId}

### Description
Sandbox endpoint to retrieve a command by ID. Mirrors the live endpoint but returns synthetic sandbox data.

### Method
GET

### Endpoint
/sandbox/commands/{commandId}

### Parameters
#### Path Parameters
- **commandId** (string) - Required - The command ID.

#### Headers
- **X-Tole-Connection-Id** (string) - Required - UUID of the sandbox connection.

### Permission
Permission of the original command.

### Response
#### Success Response (200)
Synthetic sandbox data.

```

--------------------------------

### GET /sandbox/history/operations

Source: https://tolepay.kz/ru/docs

Sandbox endpoint to retrieve operation history. Mirrors the live endpoint but returns synthetic sandbox data.

```APIDOC
## GET /sandbox/history/operations

### Description
Sandbox endpoint to retrieve operation history. Mirrors the live endpoint but returns synthetic sandbox data.

### Method
GET

### Endpoint
/sandbox/history/operations

### Parameters
#### Headers
- **X-Tole-Connection-Id** (string) - Required - UUID of the sandbox connection.

### Permission
history:read

### Response
#### Success Response (200)
Synthetic sandbox data.

```

--------------------------------

### GET /sandbox/invoices/history

Source: https://tolepay.kz/ru/docs

Sandbox endpoint to retrieve invoice history. Mirrors the live endpoint but returns synthetic sandbox data.

```APIDOC
## GET /sandbox/invoices/history

### Description
Sandbox endpoint to retrieve invoice history. Mirrors the live endpoint but returns synthetic sandbox data.

### Method
GET

### Endpoint
/sandbox/invoices/history

### Parameters
#### Headers
- **X-Tole-Connection-Id** (string) - Required - UUID of the sandbox connection.

### Permission
invoice:read

### Response
#### Success Response (200)
Synthetic sandbox data.

```

--------------------------------

### POST /recurring-invoices/{recurringInvoiceId}/run - Example request

Source: https://tolepay.kz/ru/docs

Curl command to trigger an unscheduled run for a recurring invoice. Uses Idempotency-Key header and optional expectedRevision in the body. Returns 202 Accepted.

```bash
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}'
```

--------------------------------

### GET /payment-intents/qr/{paymentIntentId}

Source: https://tolepay.kz/ru/docs

Retrieves the saved status of a QR payment intent. Provides a durable payment-intent contract for QR.

```APIDOC
## GET /payment-intents/qr/{paymentIntentId}

### Description
Retrieves the saved status of a QR payment intent. Provides a durable payment-intent contract for QR.

### Method
GET

### Endpoint
/payment-intents/qr/{paymentIntentId}

### Parameters
#### Path Parameters
- **paymentIntentId** (uuid) - Required - UUID of the Tole payment intent.

#### Header Parameters
- **X-Tole-Connection-Id** (string) - Optional - UUID of the live connection; can be omitted when a primary connection is configured.

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

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success.
- **data** (object) - Contains payment intent details.
  - **id** (uuid) - Payment intent ID.
  - **kind** (string) - Type of payment intent, e.g., "qr".
  - **status** (string) - Status of the payment intent, e.g., "pending".
  - **amount** (number) - Amount in minor units.
  - **currency** (string) - Currency code, e.g., "KZT".
  - **revision** (number) - Revision number.
  - **source** (string) - Source of the payment intent, can be null.
  - **recurringInvoiceId** (uuid) - ID of the recurring invoice, can be null.
  - **occurrenceId** (uuid) - ID of the occurrence, can be null.
  - **attemptNumber** (number) - Attempt number, can be null.

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

--------------------------------

### GET /sandbox/invoices/{operationId}

Source: https://tolepay.kz/ru/docs

Sandbox endpoint to retrieve a specific invoice by operation ID. Mirrors the live endpoint but returns synthetic sandbox data.

```APIDOC
## GET /sandbox/invoices/{operationId}

### Description
Sandbox endpoint to retrieve a specific invoice by operation ID. Mirrors the live endpoint but returns synthetic sandbox data.

### Method
GET

### Endpoint
/sandbox/invoices/{operationId}

### Parameters
#### Path Parameters
- **operationId** (string) - Required - The operation ID of the invoice.

#### Headers
- **X-Tole-Connection-Id** (string) - Required - UUID of the sandbox connection.

### Permission
invoice:read

### Response
#### Success Response (200)
Synthetic sandbox data.

```

--------------------------------

### GET /commands/{commandId}

Source: https://tolepay.kz/ru/docs

Checks an idempotent command after a 202, network interruption, or retry. The command itself determines connection and permission.

```APIDOC
## GET /commands/{commandId}

### Description
Checks an idempotent command after a 202, network interruption, or retry. The command itself determines connection and permission.

### Method
GET

### Endpoint
/commands/{commandId}

### Parameters
#### Path Parameters
- **commandId** (uuid) - Required - UUID from commandId or Location.

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

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates success.
- **data** (object) - Contains command details.
  - **commandId** (uuid) - Command ID.
  - **status** (string) - Status of the command, e.g., "succeeded".
  - **responseStatus** (number) - HTTP status of the original response.
  - **result** (object) - Result of the command.
    - **ok** (boolean) - Indicates success.
    - **data** (object) - Contains result data.
      - **id** (uuid) - ID of the created resource.
    - **commandId** (uuid) - Command ID.
  - **updatedAt** (string) - Last update timestamp.

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

--------------------------------

### GET /history/operations

Source: https://tolepay.kz/ru/docs

Retrieves operation history up to a specified calendar date UTC with cursor for next page. Requires the history:read permission.

```APIDOC
## GET /history/operations

### Description
Retrieves operation history up to a specified calendar date UTC with cursor for next page.

### Method
GET

### Endpoint
https://api.tolepay.kz/v1/history/operations

### Parameters
#### Headers
- **X-Tole-Connection-Id** (string) - Optional - UUID live-connection; can be omitted if main connection is configured.

#### Query Parameters
- **endDate** (date) - Required - YYYY-MM-DD, inclusive, UTC.
- **lastTransactionDate** (string) - Optional - Cursor from previous response.
- **statementPeriodCode** (integer) - Optional - Non-negative period code.

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

### Response
#### Success Response (200 OK)
- **ok** (boolean) - Indicates success.
- **data** (object) - Contains operation history.
  - **items** (array) - List of operations.
    - **operationId** (uuid) - Operation ID.
    - **amount** (integer) - Amount in KZT.
    - **type** (string) - Type of operation (e.g., Payment).
    - **status** (string) - Status of operation.
  - **lastTransactionDate** (string) - Cursor for next page.
  - **hasMore** (boolean) - Indicates if more pages exist.

#### Response Example
```json
{
  "ok": true,
  "data": {
    "items": [{ "operationId": "uuid", "amount": 5000, "type": "Payment", "status": "Processed" }], n    "lastTransactionDate": "…", "hasMore": false
  }
}
```
```

--------------------------------

### GET /webhook-deliveries?status=...

Source: https://tolepay.kz/ru/docs

Lists webhook deliveries, optionally filtered by status. Status can be pending, processing, delivered, or dead_letter.

```APIDOC
## GET /webhook-deliveries?status=...

### Description
Lists webhook deliveries, optionally filtered by status.

### Method
GET

### Endpoint
/webhook-deliveries

### Authentication
JWT or tole_sk_* secret

### Query Parameters
- **status** (string) - Optional - Filter by delivery status: pending, processing, delivered, dead_letter

### Response
#### Success Response (200)
- **deliveries** (array) - List of webhook deliveries

#### Response Example
{
  "deliveries": []
}
```

--------------------------------

### GET /sandbox/history/operations/{operationId}

Source: https://tolepay.kz/ru/docs

Sandbox endpoint to retrieve a specific operation by ID. Mirrors the live endpoint but returns synthetic sandbox data.

```APIDOC
## GET /sandbox/history/operations/{operationId}

### Description
Sandbox endpoint to retrieve a specific operation by ID. Mirrors the live endpoint but returns synthetic sandbox data.

### Method
GET

### Endpoint
/sandbox/history/operations/{operationId}

### Parameters
#### Path Parameters
- **operationId** (string) - Required - The operation ID.

#### Headers
- **X-Tole-Connection-Id** (string) - Required - UUID of the sandbox connection.

### Permission
history:read

### Response
#### Success Response (200)
Synthetic sandbox data.

```

--------------------------------

### Create invoice

Source: https://tolepay.kz/ru/docs

Creates a live Kaspi invoice. Requires an idempotency key for safe retries.

```bash
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"}'
```

```json
{
  "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 /recurring-invoices/{recurringInvoiceId}/occurrences - Example request

Source: https://tolepay.kz/ru/docs

Curl command to retrieve the history of occurrences for a recurring invoice, with optional limit parameter. Returns 200 OK.

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

--------------------------------

### POST /sandbox/qr

Source: https://tolepay.kz/ru/docs

Sandbox endpoint to create a QR code. Mirrors the live endpoint but returns synthetic sandbox data.

```APIDOC
## POST /sandbox/qr

### Description
Sandbox endpoint to create a QR code. Mirrors the live endpoint but returns synthetic sandbox data.

### Method
POST

### Endpoint
/sandbox/qr

### Parameters
#### Headers
- **X-Tole-Connection-Id** (string) - Required - UUID of the sandbox connection.

### Permission
qr:create

### Response
#### Success Response (201 Created)
Sandbox QR object.

#### Response Example
{
  "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
}

```

--------------------------------

### Get Operation History GET /history/operations

Source: https://tolepay.kz/ru/docs

Retrieves a list of operations up to a specified UTC date.

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

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

--------------------------------

### POST /qr

Source: https://tolepay.kz/ru/docs

Creates a dynamic QR for payment and returns paymentUrl and qrToken. Requires the qr:create permission.

```APIDOC
## POST /qr

### Description
Creates a dynamic QR for payment and returns paymentUrl and qrToken.

### Method
POST

### Endpoint
https://api.tolepay.kz/v1/qr

### Parameters
#### Headers
- **X-Tole-Connection-Id** (string) - Optional - UUID live-connection; can be omitted if main connection is configured.
- **Idempotency-Key** (string) - Required - Unique mutation key. Repeat the same request with the same key.

#### Request Body
- **amount** (integer) - Required - Amount in KZT: 1–100,000,000.
- **latitude** (number) - Optional - Latitude, -90 to 90; only together with longitude.
- **longitude** (number) - Optional - Longitude, -180 to 180; only together with latitude.
- **expiresAt** - Optional - Expiration timestamp.
- **receiptUrl** - Optional - Receipt URL.

### Request Example
```
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}'
```

### Response
#### Success Response (201 Created)
- **ok** (boolean) - Indicates success.
- **data** (object) - Contains payment details.
  - **id** (uuid) - Operation ID.
  - **kind** (string) - Always "qr".
  - **status** (string) - Status of the QR.
  - **amount** (integer) - Amount in KZT.
  - **paymentUrl** (string) - Payment URL.
  - **qrToken** (string) - QR token URL.
  - **expiresAt** (string) - Expiration timestamp.
  - **receiptUrl** (string) - Receipt URL.
- **commandId** (uuid) - Command ID.
- **replayed** (boolean) - Indicates if the request was replayed.

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

--------------------------------

### Create Dynamic QR POST /qr

Source: https://tolepay.kz/ru/docs

Creates a QR code for payment. Requires an idempotency key and amount in the request body.

```bash
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}'
```

```json
{
  "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
}
```

--------------------------------

### Пример ответа 200 OK для preview

Source: https://tolepay.kz/ru/docs

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

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

--------------------------------

### POST /sandbox/payment-intents/{paymentIntentId}/simulate request and response

Source: https://tolepay.kz/ru/docs

Simulate a payment result to transition a sandbox intent to a terminal status. Requires the X-Tole-Connection-Id header.

```bash
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"}'
```

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

--------------------------------

### Recurring-invoice lifecycle event payload example

Source: https://tolepay.kz/ru/docs

Example JSON payload for a recurring_invoice.occurrence.succeeded webhook event. Contains id, type, createdAt, and data with recurringInvoiceId, occurrenceId, attemptNumber, scheduledFor, status, paymentIntentId, and commandId.

```json
{
  "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"
  }
}
```

--------------------------------

### curl запрос к POST /recurring-invoices/preview

Source: https://tolepay.kz/ru/docs

Отправляет предпросмотр расписания: рассчитывает следующие 1-20 UTC instants без сохранения правила и без обращения в Kaspi. Требуется Bearer API key. В примере schedule monthly, timezone Asia/Almaty, count 5.

```bash
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
  }'
```

--------------------------------

### POST /sandbox/invoices

Source: https://tolepay.kz/ru/docs

Sandbox endpoint to create an invoice. Mirrors the live endpoint but returns synthetic sandbox data.

```APIDOC
## POST /sandbox/invoices

### Description
Sandbox endpoint to create an invoice. Mirrors the live endpoint but returns synthetic sandbox data.

### Method
POST

### Endpoint
/sandbox/invoices

### Parameters
#### Headers
- **X-Tole-Connection-Id** (string) - Required - UUID of the sandbox connection.

### Permission
invoice:create

### Response
#### Success Response (201 Created)
Sandbox invoice object.

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

```

--------------------------------

### GET /billing/invoices/{invoiceId}

Source: https://tolepay.kz/ru/docs

Retrieves an owner-scoped billing invoice by its ID.

```APIDOC
## GET /billing/invoices/{invoiceId}

### Description
Retrieves an owner-scoped billing invoice by its ID.

### Method
GET

### Endpoint
/billing/invoices/{invoiceId}

### Authentication
JWT

### Parameters
#### Path Parameters
- **invoiceId** (string) - Required - The ID of the invoice to retrieve.
```

--------------------------------

### POST /sandbox/payment-intents/{paymentIntentId}/simulate

Source: https://tolepay.kz/ru/docs

Simulates a payment result for a sandbox payment intent, transitioning it to a terminal status and creating a webhook event.

```APIDOC
## POST /sandbox/payment-intents/{paymentIntentId}/simulate

### Description
Simulates a payment result for a sandbox payment intent, transitioning it to a terminal status and creating a webhook event.

### Method
POST

### Endpoint
/sandbox/payment-intents/{paymentIntentId}/simulate

### Authentication
Bearer API key

### Permission
sandbox:simulate

### Parameters
#### Path Parameters
- **paymentIntentId** (uuid) - Required - UUID of the Tole payment intent.

#### Headers
- **X-Tole-Connection-Id** (string) - Required - UUID of the sandbox connection.

#### Request Body
- **status** (enum) - Required - paid | cancelled | expired | failed

### Request Example
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 -d '{"status":"paid"}'

### Response
#### Success Response (200 OK)
Simulated payment intent object.

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

```

--------------------------------

### POST /sandbox/refunds

Source: https://tolepay.kz/ru/docs

Sandbox endpoint to create a refund. Mirrors the live endpoint but returns synthetic sandbox data.

```APIDOC
## POST /sandbox/refunds

### Description
Sandbox endpoint to create a refund. Mirrors the live endpoint but returns synthetic sandbox data.

### Method
POST

### Endpoint
/sandbox/refunds

### Parameters
#### Headers
- **X-Tole-Connection-Id** (string) - Required - UUID of the sandbox connection.

### Permission
refund:create

### Response
#### Success Response (200)
Synthetic sandbox data.

```

--------------------------------

### POST /sandbox/connections request and response

Source: https://tolepay.kz/ru/docs

Create a sandbox connection using a user JWT. The request requires a displayName, and the response returns the connection details.

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

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

--------------------------------

### Get Invoice Status Response

Source: https://tolepay.kz/ru/docs

Successful response containing the invoice details and current status.

```json
{
  "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": "…"
  }
}
```

--------------------------------

### POST /billing/checkout

Source: https://tolepay.kz/ru/docs

Creates or continues a checkout session with the specified plan code.

```APIDOC
## POST /billing/checkout

### Description
Creates or continues a checkout session with the specified plan code.

### Method
POST

### Endpoint
/billing/checkout

### Authentication
JWT

### Parameters
#### Request Body
- **planCode** (string) - Required - The code of the plan to subscribe to.

### Request Example
{
  "planCode": "business"
}

### Response
#### Success Response (201 Created)
- **id** (string) - The checkout ID.
- **status** (string) - The status of the checkout (e.g., pending).
- **planCode** (string) - The plan code.
- **planName** (string) - The plan name.
- **amountKzt** (number) - The amount in KZT.
- **currency** (string) - The currency code.
- **paymentUrl** (string) - The payment URL.
- **receiptUrl** (string or null) - The receipt URL.
- **expiresAt** (string) - The expiration timestamp.
- **paidAt** (string or null) - The paid timestamp.
- **createdAt** (string) - The creation timestamp.

#### Response Example
{
  "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"
}
```