> For the complete documentation index, see [llms.txt](https://docs.xpayconnect.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xpayconnect.io/readme.md).

# Merchant API

Server-to-server API для мерчантов — ордера на приём и выплату, чеки, справочники. Единый формат ответов, подстатусы ордера, курсорная пагинация.

Merchant API — серверный API под префиксом `/v1/merchant/…`: создание ордеров на приём и выплату, их статусы, чеки и Transaction ID, аккаунт мерчанта и справочники. Запросы подписываются API-ключом ([Авторизация](/concepts/auth.md)), о событиях ордера мы сообщаем [вебхуками](/concepts/webhooks.md), а проверить интеграцию без реальных денег можно в [тестовом режиме](/concepts/sandbox.md).

## Как устроен API

| Аспект         | Как работает                                                                                                                    |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| Конверт ответа | Всегда `{ "ok": true, "data": … }` или `{ "ok": false, "error": { "code", "message", "retryable", "request_id" } }`             |
| Имена полей    | `snake_case`: `order_id`, `amount_after_fee`, `usdt.amount`                                                                     |
| Идентификаторы | `id` — наш идентификатор ордера, `order_id` — ваш                                                                               |
| Статус         | `status` (`pending` / `success` / `error`) + `substatus` (например `awaiting_payment`, `review`) + `is_final` + `cancel_reason` |
| Деньги         | Всегда строка с точностью валюты: `"2300"`, `"49.99"`                                                                           |
| Даты           | ISO 8601 UTC: `2026-04-30T13:28:57.764Z`                                                                                        |
| Список ордеров | Курсорная пагинация: `limit` + `cursor`, `has_more`, `total` по запросу                                                         |
| Ошибки         | Машинные коды из единого каталога + `details` + флаг `retryable`                                                                |
| Запросы        | `X-Request-Id` в каждом ответе (и в `error.request_id`) — указывайте его при обращении в поддержку                              |

{% hint style="info" %}
Контракт развивается без ломающих изменений: новые поля, подстатусы и коды ошибок добавляются, существующие сохраняют смысл. Игнорируйте неизвестные поля и трактуйте незнакомый `substatus` по `status` и `is_final`. Все изменения — в [Changelog](/refdata/changelog.md).
{% endhint %}

## Разделы

| Раздел                                                                                                       | Описание                                                                    |
| ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------- |
| [Быстрый старт](/quickstart.md)                                                                              | Первый ордер за 10 минут                                                    |
| [Авторизация](/concepts/auth.md) · [Вебхуки](/concepts/webhooks.md) · [Тестовый режим](/concepts/sandbox.md) | Ключ и подпись, события ордера, песочница                                   |
| [Статусы и жизненный цикл](/concepts/statuses.md)                                                            | `status`, `substatus`, `is_final`, `expires_at`, ответ `202`                |
| [Ошибки](/concepts/errors.md)                                                                                | Конверт ошибки и каталог кодов                                              |
| [Reference](/reference/create-order.md)                                                                      | Описание каждого эндпойнта из OpenAPI-спеки с примерами и кнопкой «Test it» |
| [Особенности методов](/guides/post-actions.md) · [Уникализация суммы](/guides/amount-disambiguation.md)      | Гайды по методам и странам                                                  |
| [Валюты](/refdata/currencies.md) · [Платёжные методы](/refdata/payment-methods.md)                           | Справочные данные                                                           |
| [Changelog](/refdata/changelog.md)                                                                           | История изменений контракта                                                 |

OpenAPI-спека целиком: [скачать](https://github.com/LuckyExchange/xpayconnect-backend/tree/main/docs/gitbook-v1/openapi/merchant-v1.ru.yaml).