A test cash register, xapi_test_… keys, and simulated payment outcomes (paid, declined, expired, failed): debug your integration and webhooks without Kaspi.
The sandbox is xpayment’s test mode: the same API v2 requests, the same statuses, and the same webhooks, but with no real Kaspi and no real money. You can issue an invoice, “pay” it with one button or one request, check a decline, an expiry, and an error, and make sure your webhook handler reacts correctly to every outcome.
The sandbox is for:
Test data is stored separately from live data: the sandbox does not touch your real payments, balance, or webhooks. The dashboard has a Песочница (Sandbox) section; if the mode is temporarily switched off on the server, the dashboard says the sandbox is unavailable.
| Live mode | Sandbox |
|---|---|
| The register is your Kaspi Pay cashier | One test register: API name test, name “Тестовая касса” (Test register) |
API v2 key xapi_… |
Test key xapi_test_… |
API v1 register key xdev_… |
Test key xdev_test_… |
| Kaspi processes the payment | You decide the outcome |
| Webhooks to your subscriptions | Webhooks to test subscriptions, with "environment": "sandbox" in the body |
The API address is the same: https://api.xpayment.kz/v2. The key decides what is a live request and what is a test one: a test key always goes to the sandbox, a live key to live mode. So you can switch between modes by simply replacing the key and the register name in your settings.
The rest of the sandbox works as it does live: a payment goes through the same stages (PENDING, WAITING_FOR_PAYER, a final status), webhooks are signed the same way, and refunds take the same path.
Open Песочница (Sandbox) in the dashboard. It has four sections: the register, keys, webhooks, and payments.
On first use xpayment creates a test register for you: API name test, name “Тестовая касса” (Test register). There is one per user; it needs no Kaspi cashier and no SMS code, and it cannot be deleted or renamed. You can also see it through the API:
curl https://api.xpayment.kz/v2/devices \
-H "Authorization: Bearer xapi_test_YOUR_TEST_KEY"
With a test key the list contains only the register test.
In the “Ключи” (Keys) section, create a test API v2 key xapi_test_…. Like a live key, it is shown once, and the list shows its first characters. You can have at most 10 active test keys. A key for API v1 (xdev_test_…) is issued in the same place and works on the register test.
A live key does not work in the sandbox, and a test key does not work on live data. It is best to keep test and live keys in different environment variables.
In the sandbox’s “Вебхуки” (Webhooks) section, create a test subscription: the address of your handler, the events, and a secret. These subscriptions belong to you personally, not to the organization, and receive only the events of test payments. The signature is the same as live: Verifying the webhook signature. You can check the connection with the “Тест” (Test) button or with a POST /v2/webhook-simulate request using a test key: the event goes to your test subscriptions with "environment": "sandbox".
Create a payment as you would live, but with a test key and the register test:
curl -X POST https://api.xpayment.kz/v2/payments/link \
-H "Authorization: Bearer xapi_test_YOUR_TEST_KEY" \
-H "Content-Type: application/json" \
-d '{"device_name": "test", "amount": 1500, "merchant_order_id": "order-42"}'
The payment appears in the sandbox’s “Платежи” (Payments) section. A phone invoice works too (POST /v2/payments). You can issue the same payments from the dashboard with the Выставить тестовый счёт (Issue a test invoice; a phone invoice) and Тестовая ссылка (Test link) buttons.
A test link leads to an xpayment page like …/sandbox/qr/{id} and lasts 5 minutes, like a short-lived live one. The page shows the amount and status and refreshes itself, but you cannot pay on it: you set the outcome with the sandbox buttons or the simulate request (the next section).
A test payment will not finish on its own: you choose the outcome. There are two ways.
In the sandbox’s “Платежи” (Payments) section, an unfinished payment has the buttons Оплачено (Paid), Клиент отклонил (Customer declined), Истёк (Expired), and Ошибка (Error).
curl -X POST https://api.xpayment.kz/v2/sandbox/payments/PAYMENT_ID/simulate \
-H "Authorization: Bearer xapi_test_YOUR_TEST_KEY" \
-H "Content-Type: application/json" \
-d '{"outcome": "paid"}'
outcome |
Final status | Webhook |
|---|---|---|
paid |
COMPLETED |
payment.completed |
declined |
CANCELLED |
payment.cancelled |
expired |
EXPIRED |
payment.expired |
failed |
FAILED |
payment.failed |
The payment applies the outcome at once, by the same rules as a live one: the status changes and the webhook goes to your test subscriptions. For API v1 the address is POST /v1/sandbox/payments/{id}/simulate with an xdev_test_… key.
Rules and errors:
PENDING, WAITING_FOR_PAYER, QR_TOKEN_CREATED);409 SANDBOX_OUTCOME_NOT_ALLOWED;403 SANDBOX_ONLY;outcome gives 400 VALIDATION_ERROR; someone else’s or a missing payment gives 404 PAYMENT_NOT_FOUND.Remember that
failedin xpayment is not a final status even live: Payment statuses and refunds.
paid → your order is fulfilled once, even if the webhook arrives again.declined, expired → the reservation is released and the buyer is offered a new attempt.failed → the order is not written off at once, and you check through GET /v2/payments/{payment_id}.Some values in the sandbox always produce the same error, so you can check how you handle Kaspi refusals.
| What to do | Result |
|---|---|
A phone invoice POST /v2/payments, the number ends in 7000000001 |
422 KASPI_CLIENT_NOT_FOUND: Kaspi does not know such a customer |
A phone invoice, the number ends in 7000000002 |
422 KASPI_ERROR: a Kaspi error |
| A refund of exactly 13.13 ₸ | The refund is declined: status FAILED, webhook payment.refund_failed |
Refunds in the sandbox work as they do live: they are created with POST /v2/payments/{id}/refund, processed in the background, and end with the payment.refunded or payment.refund_failed webhook. More: Payment statuses and refunds.
GET /v2/static-qr-payments/{orderNumber} with a test key returns 404 NOT_AVAILABLE_IN_SANDBOX.test.Requests that create data in the sandbox (a payment, a link, a refund, and simulating an outcome) are limited: 60 a minute and 1000 a day per user. When you exceed it, the API answers 429 RATE_LIMITED with a Retry-After header. The same requests with a live key do not count against this limit.
When everything works:
xapi_… key.device_name: "test" with the live ones.If something goes wrong, check the payment statuses and the webhook signature.