# Merchant API

Buying digital keys from a prepaid balance: catalog, availability check, purchase, order status and outcome notifications.

Base URL: `https://merchant.dbdlobby.com`. HTTPS and JSON only. Authentication: the `X-Entity-Key` header. Prices are numbers in the product currency (RUB or USD), times are ISO 8601 in UTC.

## 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.

## Endpoint reference

- [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.
- [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.
- [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_…).
- [GET /health/api](https://docs.merchant.dbdlobby.com/en/reference/health.md) — Availability check for monitoring. No authorization.

- [Interactive sandbox](https://docs.merchant.dbdlobby.com/en/sandbox)
- [llms-full.txt](https://docs.merchant.dbdlobby.com/llms-full.txt) · [OpenAPI](https://docs.merchant.dbdlobby.com/openapi.json)