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

Тестовая касса, тестовые ключи xapi_test_… и имитация исходов платежа (оплачен, отклонён, истёк, ошибка): отладьте интеграцию и вебхуки без Kaspi.

## Зачем нужна песочница

Песочница — это тестовый режим xpayment: те же запросы API v2, те же статусы и те же вебхуки, но **без реального Kaspi и без реальных денег**. Вы можете выставить счёт, «оплатить» его одной кнопкой или одним запросом, проверить отказ, истечение срока и ошибку, и убедиться, что ваш обработчик вебхуков правильно реагирует на каждый исход.

Песочница нужна, чтобы:

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

```bash
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. Эти подписки принадлежат вам лично, а не организации, и получают только события тестовых платежей. Подпись такая же, как в бою: [Проверка подписи вебхука](https://xpayment.kz/blog/webhook-security). Проверить связь можно кнопкой «Тест» или запросом `POST /v2/webhook-simulate` с тестовым ключом: событие уйдёт на ваши тестовые подписки с `"environment": "sandbox"`.

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

Создайте платёж так же, как в бою, но с тестовым ключом и кассой `test`:

```bash
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

```bash
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 — не окончательный статус даже в бою: [Статусы платежей и возвраты](https://xpayment.kz/blog/payment-statuses-and-refunds).

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

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`. Подробнее: [Статусы платежей и возвраты](https://xpayment.kz/blog/payment-statuses-and-refunds).

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

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

- **Реального Kaspi.** Статус определяет исход, который вы выбрали. Kaspi не получает ничего, поэтому настоящие ошибки сессии и сети проверить нельзя.
- **Статического QR.** `GET /v2/static-qr-payments/{orderNumber}` с тестовым ключом возвращает `404 NOT_AVAILABLE_IN_SANDBOX`.
- **Своих касс.** В песочнице одна касса, `test`.
- **Остальных инструментов.** Тестовые платежи не затрагивают ваш баланс. Биллинг, подписки, регулярные платежи и онлайн-запись в песочнице недоступны.

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

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

### Очистка

- Кнопка **«Очистить песочницу»** в кабинете удаляет ваши тестовые платежи вместе с событиями, возвратами и доставками вебхуков.
- Автоматически xpayment удаляет тестовые платежи **старше 30 дней**.
- Тестовая касса, тестовые ключи и тестовые подписки остаются.

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

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

1. Подключите боевую кассу: [Подключение кассы и ключ API v2](https://xpayment.kz/blog/device-setup).
2. Создайте боевой ключ `xapi_…`.
3. Замените в настройках тестовый ключ и `device_name: "test"` на боевые.
4. Создайте боевую подписку на вебхуки в разделе «Вебхуки».
5. Сделайте первый реальный платёж на небольшую сумму и отмените или верните его.

Если что-то пойдёт не так, проверьте [статусы платежей](https://xpayment.kz/blog/payment-statuses-and-refunds) и [подпись вебхука](https://xpayment.kz/blog/webhook-security).

## Читайте также
- [Удалённые платежи](https://xpayment.kz/blog/direct-payment)
- [Платёжные ссылки](https://xpayment.kz/blog/payment-link)
- [Webhooks xpayment](https://xpayment.kz/blog/webhooks)

---

Источник: https://xpayment.kz/blog/sandbox
