Тестовая касса, тестовые ключи xapi_test_… и имитация исходов платежа (оплачен, отклонён, истёк, ошибка): отладьте интеграцию и вебхуки без Kaspi.
Песочница — это тестовый режим xpayment: те же запросы API v2, те же статусы и те же вебхуки, но без реального Kaspi и без реальных денег. Вы можете выставить счёт, «оплатить» его одной кнопкой или одним запросом, проверить отказ, истечение срока и ошибку, и убедиться, что ваш обработчик вебхуков правильно реагирует на каждый исход.
Песочница нужна, чтобы:
Тестовые данные хранятся отдельно от боевых: ваши реальные платежи, баланс и вебхуки песочница не затрагивает. Раздел «Песочница» есть в кабинете; если режим на сервере временно выключен, кабинет сообщит, что песочница недоступна.
| Боевой режим | Песочница |
|---|---|
| Касса — ваш кассир Kaspi Pay | Одна тестовая касса: имя для API test, название «Тестовая касса» |
Ключ API v2 xapi_… |
Тестовый ключ xapi_test_… |
Ключ кассы API v1 xdev_… |
Тестовый ключ xdev_test_… |
| Платёж обрабатывает Kaspi | Исход определяете вы |
| Вебхуки на ваши подписки | Вебхуки на тестовые подписки, в теле "environment": "sandbox" |
Адрес API тот же: https://api.xpayment.kz/v2. Что боевой запрос, а что тестовый, определяет ключ: тестовый ключ всегда попадает в песочницу, боевой — в боевой режим. Поэтому переключаться между режимами можно, просто заменив ключ и имя кассы в настройках.
Остальное в песочнице работает так же, как в бою: платёж проходит те же стадии (PENDING, WAITING_FOR_PAYER, итоговый статус), вебхуки подписываются так же, возвраты идут тем же путём.
Откройте в кабинете «Песочница». Там четыре раздела: касса, ключи, вебхуки и платежи.
При первом обращении xpayment создаёт вам тестовую кассу: имя для API test, название «Тестовая касса». Она одна на пользователя, не требует кассира Kaspi и SMS-кода, не удаляется и не переименовывается. Её можно увидеть и через API:
curl https://api.xpayment.kz/v2/devices \
-H "Authorization: Bearer xapi_test_ВАШ_ТЕСТОВЫЙ_КЛЮЧ"
С тестовым ключом в списке будет только касса test.
В разделе «Ключи» создайте тестовый ключ API v2 xapi_test_…. Он, как и боевой, показывается один раз, а в списке видны его первые символы. Активных тестовых ключей может быть не более 10. Ключ для API v1 (xdev_test_…) выпускается там же и работает на кассе test.
Боевой ключ в песочнице не работает, а тестовый не работает на боевых данных. Хранить тестовые и боевые ключи лучше в разных переменных окружения.
В разделе «Вебхуки» песочницы создайте тестовую подписку: адрес вашего обработчика, события и secret. Эти подписки принадлежат вам лично, а не организации, и получают только события тестовых платежей. Подпись такая же, как в бою: Проверка подписи вебхука. Проверить связь можно кнопкой «Тест» или запросом POST /v2/webhook-simulate с тестовым ключом: событие уйдёт на ваши тестовые подписки с "environment": "sandbox".
Создайте платёж так же, как в бою, но с тестовым ключом и кассой test:
curl -X POST https://api.xpayment.kz/v2/payments/link \
-H "Authorization: Bearer xapi_test_ВАШ_ТЕСТОВЫЙ_КЛЮЧ" \
-H "Content-Type: application/json" \
-d '{"device_name": "test", "amount": 1500, "merchant_order_id": "order-42"}'
Платёж появится в разделе «Платежи» песочницы. Счёт на телефон тоже работает (POST /v2/payments). Тот же платёж можно выставить из кабинета кнопками «Выставить тестовый счёт» (счёт на телефон) и «Тестовая ссылка».
Тестовая ссылка ведёт на страницу xpayment вида …/sandbox/qr/{id} и действует 5 минут, как короткоживущая боевая. Страница показывает сумму и статус и обновляется сама, но оплатить на ней нельзя: исход вы задаёте кнопками «Песочницы» или запросом simulate (следующий раздел).
Тестовый платёж сам не завершится: исход выбираете вы. Есть два способа.
В разделе «Платежи» песочницы у незавершённого платежа есть кнопки «Оплачено», «Клиент отклонил», «Истёк» и «Ошибка».
curl -X POST https://api.xpayment.kz/v2/sandbox/payments/PAYMENT_ID/simulate \
-H "Authorization: Bearer xapi_test_ВАШ_ТЕСТОВЫЙ_КЛЮЧ" \
-H "Content-Type: application/json" \
-d '{"outcome": "paid"}'
outcome |
Итоговый статус | Вебхук |
|---|---|---|
paid |
COMPLETED |
payment.completed |
declined |
CANCELLED |
payment.cancelled |
expired |
EXPIRED |
payment.expired |
failed |
FAILED |
payment.failed |
Платёж применяет исход сразу, теми же правилами, что и боевой: статус меняется, а вебхук уходит на ваши тестовые подписки. Для API v1 адрес — POST /v1/sandbox/payments/{id}/simulate с ключом xdev_test_….
Правила и ошибки:
PENDING, WAITING_FOR_PAYER, QR_TOKEN_CREATED);409 SANDBOX_OUTCOME_NOT_ALLOWED;403 SANDBOX_ONLY;outcome — 400 VALIDATION_ERROR; чужой или несуществующий платёж — 404 PAYMENT_NOT_FOUND.Помните, что
failedв xpayment — не окончательный статус даже в бою: Статусы платежей и возвраты.
paid → ваш заказ выполняется один раз, даже если вебхук придёт повторно.declined, expired → резерв снимается, покупателю предлагается новая попытка.failed → заказ не списывается сразу, вы сверяетесь через GET /v2/payments/{payment_id}.Некоторые значения в песочнице всегда дают одну и ту же ошибку, чтобы вы могли проверить обработку отказов Kaspi.
| Что сделать | Результат |
|---|---|
Счёт на телефон POST /v2/payments, номер заканчивается на 7000000001 |
422 KASPI_CLIENT_NOT_FOUND: Kaspi не знает такого клиента |
Счёт на телефон, номер заканчивается на 7000000002 |
422 KASPI_ERROR: ошибка Kaspi |
| Возврат ровно на 13.13 ₸ | Возврат отклоняется: статус FAILED, вебхук payment.refund_failed |
Возвраты в песочнице работают как в бою: создаются через POST /v2/payments/{id}/refund, обрабатываются в фоне и завершаются вебхуком payment.refunded или payment.refund_failed. Подробнее: Статусы платежей и возвраты.
GET /v2/static-qr-payments/{orderNumber} с тестовым ключом возвращает 404 NOT_AVAILABLE_IN_SANDBOX.test.Запросы, которые создают данные в песочнице (платёж, ссылка, возврат и имитация исхода), ограничены: 60 в минуту и 1000 в сутки на пользователя. При превышении API отвечает 429 RATE_LIMITED с заголовком Retry-After. Те же запросы с боевым ключом этим лимитом не считаются.
Когда всё работает:
xapi_….device_name: "test" на боевые.Если что-то пойдёт не так, проверьте статусы платежей и подпись вебхука.