Kaspi invoices from your own system
Your CRM or website issues a Kaspi invoice for any amount to a customer by phone number. The customer receives the invoice in the Kaspi app and pays it. Once the payment goes through, your webhook receives the kaspi_invoice_paid event: use it to close the order and, if needed, message the customer via POST /v1/messages/send.
Before you start
- A Kaspi Pay cashier is connected in the dashboard: Settings → Integrations → Kaspi Pay. You need a separate number with the «Cashier» role.
- You have an active Kaspi Pay plan: «Start» (up to 150 payments per month per cash register) or «Unlimited». Pay for it in the dashboard: Connectors → Kaspi Pay. A 7-day trial starts when you first connect a cashier. If your WazzaBee CRM is active (trial or paid), invoices are free.
- Kaspi invoices are enabled for your API key. WazzaBee support enables them at your request; for other keys the methods return a 403 error.
- The key's webhook is set up via PATCH /v1/webhooks. Kaspi events are delivered to it without a separate subscription.
Protection against extra invoices
- No more than 5 invoices per minute and 100 per day per key. If you need more, contact support.
- A repeated request with the same
externalIddoes not create a second invoice; it returns the first one with"duplicate": true. - If an unpaid invoice for the same number and the same amount already exists from the last 30 minutes, no new one is created and the existing invoice is returned.
- No more than 300 invoices per day per cashier across all sources: API, menu bot and CRM deals.
- If customers decline or do not pay 10 or more invoices of a key within a day and that is more than half of the closed ones, Kaspi invoices for the key are stopped automatically (error
kaspi_auto_stopped). Contact support to turn them back on.
POST /v1/kaspi/invoices
Issue an invoice.
POST https://api.wazzabee.com/api-gateway/v1/kaspi/invoices
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
| Parameter | Type | Required | Description |
|---|---|---|---|
phone | string | ✅ | The customer's Kaspi number, Kazakhstan: +77011234567, 87011234567 or 7011234567 |
amount | number | ✅ | Amount in tenge, greater than 0 and no more than 5 000 000 |
comment | string | No | Invoice comment up to 200 characters, for example the order number and the item. The customer sees it in Kaspi |
externalId | string | No | Order number in your system, up to 100 characters. Protects against a double invoice when a request is retried |
curl -X POST "https://api.wazzabee.com/api-gateway/v1/kaspi/invoices" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"phone": "+77011234567", "amount": 15000, "comment": "Order 1024, phone case", "externalId": "1024"}'
Response 201 (new invoice) or 200 (repeat, "duplicate": true):
{
"success": true,
"duplicate": false,
"invoice": {
"invoiceId": "uuid",
"externalId": "1024",
"phone": "+77011234567",
"amount": 15000,
"comment": "Order 1024, phone case",
"status": "pending",
"createdAt": "2026-11-17T14:00:00.000Z",
"paidAt": null
}
}
Invoice statuses: pending (awaiting payment), paid (paid), expired (expired), cancelled (cancelled), unknown (Kaspi gave no response within 3 days).
GET /v1/kaspi/invoices/{invoiceId}
An invoice by its invoiceId. Response: {"success": true, "invoice": {...}}. The status is updated once a minute.
GET /v1/kaspi/invoices
Invoices of your key, newest first. Query string parameters: from and to (ISO 8601 date), status (pending, paid, expired, cancelled, unknown), limit (1–200, default 50).
GET https://api.wazzabee.com/api-gateway/v1/kaspi/invoices?from=2026-11-01T00:00:00Z&status=paid
POST /v1/kaspi/invoices/{invoiceId}/cancel
Cancel an unpaid invoice. Response: {"success": true, "invoice": {..., "status": "cancelled"}}. No webhook is sent for a cancellation you made yourself; the result comes straight in the response.
Webhook events
| Event | When |
|---|---|
kaspi_invoice_paid | The customer paid the invoice |
kaspi_invoice_expired | The invoice payment period has expired |
kaspi_invoice_cancelled | The customer declined the invoice or it was cancelled in Kaspi |
{
"event": "kaspi_invoice_paid",
"invoice": {
"invoiceId": "uuid",
"externalId": "1024",
"phone": "+77011234567",
"amount": 15000,
"comment": "Order 1024, phone case",
"status": "paid",
"createdAt": "2026-11-17T14:00:00.000Z",
"paidAt": "2026-11-17T14:03:10.000Z"
},
"timestamp": "2026-11-17T14:03:40.000Z"
}
The event arrives within a minute of the status change, signed and with retries, like all other WazzaBee webhooks. You can double-check the status via GET /v1/kaspi/invoices/{invoiceId}.
Possible errors
| Code | error | Reason |
|---|---|---|
400 | bad_phone, bad_amount, bad_external_id | Invalid number, amount or externalId |
402 | no_tariff | No active Kaspi Pay plan and the trial has ended. Pay for a plan: Connectors → Kaspi Pay |
402 | plan_limit | The «Start» plan payment limit for this month has been reached |
403 | kaspi_not_enabled | Kaspi invoices are not enabled for this key |
403 | kaspi_auto_stopped | Invoices for the key were stopped automatically due to mass refusals, support can re-enable them |
404 | not_found | The invoice was not found among your key's invoices |
409 | not_connected, needs_reauth | The cashier is not connected or needs to be reconnected in the dashboard |
409 | not_cancellable | The invoice is already paid or closed |
429 | rate_limit_minute, rate_limit_day | The key's invoice limit has been exceeded |
429 | kassa_day_limit | The cashier has issued 300 invoices today, try again tomorrow |
502 | kaspi_error | Kaspi did not accept the request, please try again later |
