Purchases and orders

Purchase a product

Creates an order, charges its price to the balance and returns the key.

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

X-Entity-Keyapplication/jsoncharges balanceMarkdown version

The price is reserved from the balance when the order is created. If the order ends up not fulfilled (failed/cancelled), the money returns to the balance automatically.

A manually fulfilled product completes immediately (201). An automatically fulfilled product is bought from the supplier: usually a few seconds, but if it takes longer than ~50 seconds you get 202 with status pending — the order keeps going. Learn the outcome from the webhook or GET /orders/{id}.

Always send an idempotencyKey. If the connection dropped or timed out, repeat the request with the same key: you get the outcome of the original order, not a second purchase.

Headers

Name	Type	Description
`X-Entity-Key`required	string	Client access key. See “Authentication”.
`Content-Type`required	string	`application/json`, otherwise `415`.

Path parameters

Name	Type	Description
`productId`required	integer	Product ID from the catalog. Example: `12`

Request body

JSON object, up to 10 KB. All fields are optional — {} is valid.

Name	Type	Description
`idempotencyKey`	string	Your unique purchase key: 1–128 printable ASCII characters, no spaces, case-sensitive. A repeat with the same key creates no second order and charges nothing twice — it returns the outcome of the first request with `replayed: true`. Strongly recommended (may become mandatory). Example: `order-7731`
`webhookUrl`	string (URL)	Where to send the notification about the order outcome. https only, up to 2048 characters, no username/password in the URL, not localhost or internal addresses. Example: `https://shop.example.com/hooks/merchant`

Responses

201 Created — key is the supplier's array of keys; the key itself is in serial, type is text or an image. Manually fulfilled products have no key field.

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"
      }
    ]
  }
}