Песочница xpayment: тестовые платежи без реальных денег

Тестовая касса, тестовые ключи 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, итоговый статус), вебхуки подписываются так же, возвраты идут тем же путём.

Подготовка

Откройте в кабинете «Песочница». Там четыре раздела: касса, ключи, вебхуки и платежи.

1. Тестовая касса

При первом обращении xpayment создаёт вам тестовую кассу: имя для API test, название «Тестовая касса». Она одна на пользователя, не требует кассира Kaspi и SMS-кода, не удаляется и не переименовывается. Её можно увидеть и через API:

curl https://api.xpayment.kz/v2/devices \
  -H "Authorization: Bearer xapi_test_ВАШ_ТЕСТОВЫЙ_КЛЮЧ"

С тестовым ключом в списке будет только касса test.

2. Тестовый ключ

В разделе «Ключи» создайте тестовый ключ API v2 xapi_test_…. Он, как и боевой, показывается один раз, а в списке видны его первые символы. Активных тестовых ключей может быть не более 10. Ключ для API v1 (xdev_test_…) выпускается там же и работает на кассе test.

Боевой ключ в песочнице не работает, а тестовый не работает на боевых данных. Хранить тестовые и боевые ключи лучше в разных переменных окружения.

3. Тестовый вебхук

В разделе «Вебхуки» песочницы создайте тестовую подписку: адрес вашего обработчика, события и secret. Эти подписки принадлежат вам лично, а не организации, и получают только события тестовых платежей. Подпись такая же, как в бою: Проверка подписи вебхука. Проверить связь можно кнопкой «Тест» или запросом POST /v2/webhook-simulate с тестовым ключом: событие уйдёт на ваши тестовые подписки с "environment": "sandbox".

4. Первый тестовый платёж

Создайте платёж так же, как в бою, но с тестовым ключом и кассой 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 (следующий раздел).

Имитация исхода платежа

Тестовый платёж сам не завершится: исход выбираете вы. Есть два способа.

В кабинете

В разделе «Платежи» песочницы у незавершённого платежа есть кнопки «Оплачено», «Клиент отклонил», «Истёк» и «Ошибка».

Через API

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_….

Правила и ошибки:

Помните, что failed в xpayment — не окончательный статус даже в бою: Статусы платежей и возвраты.

Что стоит проверить

  1. Успех: paid → ваш заказ выполняется один раз, даже если вебхук придёт повторно.
  2. Отказ и истечение: declined, expired → резерв снимается, покупателю предлагается новая попытка.
  3. Ошибка: failed → заказ не списывается сразу, вы сверяетесь через GET /v2/payments/{payment_id}.
  4. Подпись: вебхук с неверной подписью отклоняется, правильный — принимается.
  5. Повтор: если ваш обработчик отвечает не-2xx, вебхук повторяется (до трёх попыток), а заказ всё равно выполняется один раз.

Предсказуемые ошибки

Некоторые значения в песочнице всегда дают одну и ту же ошибку, чтобы вы могли проверить обработку отказов 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. Подробнее: Статусы платежей и возвраты.

Ограничения и очистка

Чего в песочнице нет

Лимиты запросов

Запросы, которые создают данные в песочнице (платёж, ссылка, возврат и имитация исхода), ограничены: 60 в минуту и 1000 в сутки на пользователя. При превышении API отвечает 429 RATE_LIMITED с заголовком Retry-After. Те же запросы с боевым ключом этим лимитом не считаются.

Очистка

Переход на боевой режим

Когда всё работает:

  1. Подключите боевую кассу: Подключение кассы и ключ API v2.
  2. Создайте боевой ключ xapi_….
  3. Замените в настройках тестовый ключ и device_name: "test" на боевые.
  4. Создайте боевую подписку на вебхуки в разделе «Вебхуки».
  5. Сделайте первый реальный платёж на небольшую сумму и отмените или верните его.

Если что-то пойдёт не так, проверьте статусы платежей и подпись вебхука.