Покупки и заказы

Покупка товара

Создаёт заказ, списывает его стоимость с баланса и выдаёт ключ.

POSThttps://merchant.dbdlobby.com/purchase/{productId}

X-Entity-Keyapplication/jsonсписывает балансMarkdown-версия

Стоимость резервируется с баланса в момент создания заказа. Если заказ в итоге не выполнен (failed/cancelled), деньги возвращаются на баланс автоматически.

Товар с ручной выдачей завершается сразу (201). Товар с автоматической выдачей покупается у поставщика: обычно это несколько секунд, но если не уложились в ~50 секунд, вы получите 202 со статусом pending — заказ продолжит выполняться. Узнать исход можно через вебхук или GET /orders/{id}.

Всегда передавайте idempotencyKey. Если соединение оборвалось или пришёл таймаут — повторите запрос с тем же ключом: вы получите исход исходного заказа, а не вторую покупку.

Заголовки

Имя	Тип	Описание
`X-Entity-Key`обязателен	string	Ключ доступа клиента. См. «Аутентификация».
`Content-Type`обязателен	string	`application/json` — иначе `415`.

Параметры пути

Имя	Тип	Описание
`productId`обязателен	integer	ID товара из каталога. Пример: `12`

Тело запроса

JSON-объект, не больше 10 КБ. Все поля необязательны — можно отправить {}.

Имя	Тип	Описание
`idempotencyKey`	string	Ваш уникальный ключ покупки: 1–128 печатных ASCII-символов без пробелов, регистр важен. Повтор с тем же ключом не создаёт второй заказ и не списывает деньги второй раз — возвращает исход первого запроса с `replayed: true`. Настоятельно рекомендуется (может стать обязательным). Пример: `order-7731`
`webhookUrl`	string (URL)	Куда отправить уведомление об исходе заказа. Только https, до 2048 символов, без логина/пароля в URL, не localhost и не внутренние адреса. Пример: `https://shop.example.com/hooks/merchant`

Ответы

201 Created — key — массив ключей от поставщика; сам ключ в поле serial, type — text или изображение. У товаров с ручной выдачей поля key нет.

application/json

{
  "status": "success",
  "order": {
    "id": 1842,
    "productId": 12,
    "quantity": 1,
    "price": 1490,
    "currency": "RUB",
    "status": "completed",
    "failureReason": null,
    "idempotencyKey": "order-7731",
    "webhookStatus": "pending",
    "createdAt": "2026-11-13T12:36:53.000Z",
    "updatedAt": "2026-11-13T12:37:10.000Z",
    "key": [
      {
        "serial": "ABCDE-FGHIJ-KLMNO",
        "type": "text",
        "name": "Dead by Daylight"
      }
    ]
  }
}