xpayment Sandbox: Test Payments Without Real Money

A test cash register, xapi_test_… keys, and simulated payment outcomes (paid, declined, expired, failed): debug your integration and webhooks without Kaspi.

Why you need the sandbox

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.

How it is organized

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.

Setup

Open Песочница (Sandbox) in the dashboard. It has four sections: the register, keys, webhooks, and payments.

1. The test register

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.

2. A test key

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.

3. A test webhook

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

4. The first test payment

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).

Simulating a payment outcome

A test payment will not finish on its own: you choose the outcome. There are two ways.

In the dashboard

In the sandbox’s “Платежи” (Payments) section, an unfinished payment has the buttons Оплачено (Paid), Клиент отклонил (Customer declined), Истёк (Expired), and Ошибка (Error).

Through the API

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:

Remember that failed in xpayment is not a final status even live: Payment statuses and refunds.

What to check

  1. Success: paid → your order is fulfilled once, even if the webhook arrives again.
  2. Decline and expiry: declined, expired → the reservation is released and the buyer is offered a new attempt.
  3. Error: failed → the order is not written off at once, and you check through GET /v2/payments/{payment_id}.
  4. Signature: a webhook with a wrong signature is rejected, a correct one is accepted.
  5. Retry: if your handler answers non-2xx, the webhook is retried (up to three attempts), and the order is still fulfilled once.

Predictable errors

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.

Limits and cleanup

What the sandbox does not have

Request limits

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.

Cleanup

Switching to live mode

When everything works:

  1. Connect a live register: Connecting a cash register and getting an API v2 key.
  2. Create a live xapi_… key.
  3. In your settings, replace the test key and device_name: "test" with the live ones.
  4. Create a live webhook subscription in the Вебхуки (Webhooks) section.
  5. Make the first real payment for a small amount and cancel or refund it.

If something goes wrong, check the payment statuses and the webhook signature.