# DBD Merchant API

> Server-to-server HTTP API (DbDLobby) for buying digital game keys from a prepaid balance. Base URL: https://merchant.dbdlobby.com. Auth: header X-Entity-Key. Documentation is available in English (/en) and Russian (/ru).

Every page has a Markdown version: append `.md` to its URL or send `Accept: text/markdown`.

- [Full documentation, English](https://docs.merchant.dbdlobby.com/llms-full.txt): every endpoint, every response with examples, all guides.
- [Full documentation, Russian](https://docs.merchant.dbdlobby.com/ru/llms-full.txt)
- [OpenAPI 3.1](https://docs.merchant.dbdlobby.com/openapi.json): machine-readable spec for code generation.

## Guides

- [Authentication](https://docs.merchant.dbdlobby.com/en/guides/authentication.md): Every request except /health/api carries the client key in the X-Entity-Key header.
- [Purchases and order status](https://docs.merchant.dbdlobby.com/en/guides/order-lifecycle.md): How a purchase works, when money is charged and returned, and where to get the key.
- [Idempotency](https://docs.merchant.dbdlobby.com/en/guides/idempotency.md): How to safely retry a purchase after a timeout or a dropped connection.
- [Webhooks](https://docs.merchant.dbdlobby.com/en/guides/webhooks.md): A notification to your server when an order reaches a final status.
- [Errors](https://docs.merchant.dbdlobby.com/en/guides/errors.md): Error format, response codes and what to do about them.
- [Limits](https://docs.merchant.dbdlobby.com/en/guides/limits.md): How many requests you can make and what limits apply to the data.

## Endpoints

### Catalog

- [GET /products](https://docs.merchant.dbdlobby.com/en/reference/list-products.md): The whole catalog with prices and an “on sale” flag.
- [GET /products/{id}/info](https://docs.merchant.dbdlobby.com/en/reference/product-info.md): One product: title, price, currency, region, platform, status, images.
- [GET /products/{id}/availability](https://docs.merchant.dbdlobby.com/en/reference/product-availability.md): A live check: can the product be bought right now.

### Purchases and orders

- [POST /purchase/{productId}](https://docs.merchant.dbdlobby.com/en/reference/purchase.md): Creates an order, charges its price to the balance and returns the key.
- [GET /orders/{id}](https://docs.merchant.dbdlobby.com/en/reference/get-order.md): Order status, and the key once the order is completed.

### Sandbox

- [GET /sandbox/products](https://docs.merchant.dbdlobby.com/en/reference/sandbox-products.md): A fixed test catalog.
- [POST /sandbox/purchase/{productId}](https://docs.merchant.dbdlobby.com/en/reference/sandbox-purchase.md): A simulated purchase with no money.
- [GET /sandbox/orders/{id}](https://docs.merchant.dbdlobby.com/en/reference/sandbox-order.md): A test order by ID (sandbox_…).

### Service

- [GET /health/api](https://docs.merchant.dbdlobby.com/en/reference/health.md): Availability check for monitoring. No authorization.

## Optional

- [Interactive sandbox](https://docs.merchant.dbdlobby.com/en/sandbox): send requests from the browser without spending money.
- [Обзор (ru)](https://docs.merchant.dbdlobby.com/ru)