> 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-ключом ([Авторизация](https://docs.xpayconnect.io/concepts/auth.md)), о событиях ордера мы сообщаем [вебхуками](https://docs.xpayconnect.io/concepts/webhooks.md), а проверить интеграцию без реальных денег можно в [тестовом режиме](https://docs.xpayconnect.io/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](https://docs.xpayconnect.io/refdata/changelog.md).
{% endhint %}

## Разделы

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

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