# Покупка и статусы заказа

Как проходит покупка, когда списываются и возвращаются деньги, где взять ключ.

## Шаги

1. Перед покупкой можно проверить наличие: [GET /products/{id}/availability](https://docs.merchant.dbdlobby.com/ru/reference/product-availability).
2. [POST /purchase/{productId}](https://docs.merchant.dbdlobby.com/ru/reference/purchase) с `idempotencyKey`. Заказ создаётся, и стоимость сразу резервируется с баланса — в одной операции. Если денег не хватает, заказ не создаётся (`402`).
3. Товар с ручной выдачей завершается сразу. Товар с автоматической выдачей покупается у поставщика, после получения ключа заказ ещё короткое время проверяется и только потом становится `completed`.
4. Ключ приходит в поле `key` ответа покупки или [GET /orders/{id}](https://docs.merchant.dbdlobby.com/ru/reference/get-order). В вебхуке ключа нет.

## Статусы

| status | Значение | Деньги |
|---|---|---|
| `pending` | Выполняется. Дождитесь вебхука или опрашивайте заказ раз в 5–10 секунд. | Зарезервированы |
| `completed` | Выполнен, ключ доступен. | Списаны |
| `failed` | Не выполнен, причина в `failureReason`. | Возвращены |
| `cancelled` | Отменён поставщиком. | Возвращены |

`completed`, `failed` и `cancelled` — окончательные: статус больше не меняется.

## Ответ 202

Если покупка у поставщика не уложилась примерно в 50 секунд, API отвечает `202` с заказом в статусе `pending`. Это не ошибка и не повод покупать снова: заказ продолжает выполняться. Узнайте исход через вебхук или `GET /orders/{id}`. В редких случаях, когда исход нужно перепроверить, заказ остаётся в `pending` дольше — деньги всё это время зарезервированы и вернутся, если заказ не будет выполнен.

> [!NOTE]
> Ставьте таймаут HTTP-клиента не меньше 90 секунд: покупка может длиться до ~50 секунд.