Kaspi invoices via API

    4 min read
    ·
    7 views
    ·
    Updated 11/18/2026

    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 externalId does 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
    ParameterTypeRequiredDescription
    phonestring✅The customer's Kaspi number, Kazakhstan: +77011234567, 87011234567 or 7011234567
    amountnumber✅Amount in tenge, greater than 0 and no more than 5 000 000
    commentstringNoInvoice comment up to 200 characters, for example the order number and the item. The customer sees it in Kaspi
    externalIdstringNoOrder 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

    EventWhen
    kaspi_invoice_paidThe customer paid the invoice
    kaspi_invoice_expiredThe invoice payment period has expired
    kaspi_invoice_cancelledThe 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

    CodeerrorReason
    400bad_phone, bad_amount, bad_external_idInvalid number, amount or externalId
    402no_tariffNo active Kaspi Pay plan and the trial has ended. Pay for a plan: Connectors → Kaspi Pay
    402plan_limitThe «Start» plan payment limit for this month has been reached
    403kaspi_not_enabledKaspi invoices are not enabled for this key
    403kaspi_auto_stoppedInvoices for the key were stopped automatically due to mass refusals, support can re-enable them
    404not_foundThe invoice was not found among your key's invoices
    409not_connected, needs_reauthThe cashier is not connected or needs to be reconnected in the dashboard
    409not_cancellableThe invoice is already paid or closed
    429rate_limit_minute, rate_limit_dayThe key's invoice limit has been exceeded
    429kassa_day_limitThe cashier has issued 300 invoices today, try again tomorrow
    502kaspi_errorKaspi did not accept the request, please try again later