Справочник API

Каждый endpoint ниже говорит на JSON, живёт под https://api.infraio.xyz (prod) или https://api-dev.infraio.xyz (test) и аутентифицируется через HMAC-SHA256 — см. Аутентификация для ритуала подписания и Ошибки для формы конверта ошибки.

Эта страница — индекс. Каждая строка ссылается на самый детальный существующий текст; если строка ссылается только на путь, endpoint существует сегодня, но описан внутри соответствующей страницы концепции, а не на собственной справочной странице.

Префиксы путей gateway и их модель аутентификации:

/b2b/v1/* — подписано HMAC вашим secret-ключом (sk_…). Backend-уровень мерчанта.
/payment/v1/* — Bearer JWT (сессии панели). Используется фронтендом панели мерчанта; не для сторонних интеграторов.
/pub/v1/* — bearer-of-truth внутри пути (rfqt_… токен для refund-request). Без credential’ов. Безопасно вызывать из браузера.
/checkout/:key/* — публичный префикс для потока размещённого checkout. key — это cst_… session_key, возвращённый при создании; вызывает только браузер покупателя. Без credential’ов.

Checkout

Метод	Путь	Назначение	Заметки
`POST`	`/b2b/v1/checkout-sessions/quick`	Создание сессии одним вызовом — заказ + checkout-session создаются вместе.	См. Быстрый старт для тела запроса и примера.
`POST`	`/b2b/v1/checkout-sessions`	Создание сессии под существующий заказ. Используйте, когда у вашей платформы уже своя модель заказа и вы хотите одну сессию на попытку.	Двухшаговый поток.
`GET`	`/b2b/v1/checkout-sessions/by-order/{order_id}`	Список всех сессий, когда-либо созданных для заказа.	Полезно, когда покупатель забросил сессию и вы хотите показать предыдущие попытки в своей панели.
`GET`	`/checkout/{session_key}`	Публичный — размещённая страница checkout запрашивает это. Только поля для покупателя (без внутренних ссылок).	Без подписи; принимает `session_key` как bearer-of-truth.
`POST`	`/checkout/{session_key}/intent`	Публичный — выбор способа оплаты на размещённой странице. Создаёт `PaymentIntent` с депозитным адресом.	Вызывается checkout-web при выборе способа пользователем.
`POST`	`/checkout/{session_key}/verify`	Публичный — позволяет покупателю вставить tx hash, чтобы сократить ожидание подтверждения.	Если hash неверный, передаёт управление chain watcher’у.

Заказы

Заказы — это вневременная биллинговая сущность. Один заказ может стоять за несколькими сессиями checkout (например, покупатель забросил и повторил попытку).

Метод	Путь	Назначение	Заметки
`POST`	`/b2b/v1/orders`	Создание заказа без сессии.	Используйте, когда хотите потом отправить покупателю платёжную ссылку, а не редиректить его сразу.
`GET`	`/b2b/v1/orders/{id}`	Чтение одного заказа с позициями и статусом.	Статус: `PENDING` → `PAID` \| `PARTIAL_PAID` \| `CANCELED`. После возврата: `PARTIALLY_REFUNDED` \| `REFUNDED`.
`GET`	`/b2b/v1/orders/by-merchant/{merchant_id}`	Список ваших заказов, курсорная пагинация.	См. Курсорная пагинация для протокола курсора.
`PATCH`	`/b2b/v1/orders/{id}/cancel`	Отметить неоплаченный заказ отменённым. Отправляет `order.canceled`.	Не сработает, если заказ уже оплачен.
`PATCH`	`/b2b/v1/orders/{id}/reopen`	Откатить авто-отмену (`canceled_reason=payment_timeout`).	Полезно, если покупатель вернулся после истечения TTL.

Возвраты

См. Страницу концепции «Возвраты» для потока saga и жизненного цикла токена.

Инициированные мерчантом

Метод	Путь	Назначение	Заметки
`POST`	`/b2b/v1/merchants/{merchant_id}/refunds`	Возврат, инициированный мерчантом. Автоматически одобряется (пропускает `PENDING`).	Отправляет `payment.refund.approved` сразу.

Инициированные клиентом — refund-request токены

Покупатель заполняет форму возврата на нашей размещённой странице; вы только генерируете токен и доставляете URL. Два пути выпуска (HMAC для backend’ов, JWT для панели), три публичных пути по токену (чтение контекста, отправка, запрос обновления) и два пути только для панели для обработки обновлений.

Метод	Путь	Аутентификация	Назначение
`POST`	`/b2b/v1/merchants/{merchant_id}/refund-requests`	HMAC (`sk_…`)	Выпуск токена из вашего backend’а. Тело: `{ref_type, ref_value, amount, ttl_seconds?, metadata?, hide_summary?, hide_header?}`. `ref_type` — одно из `order_id` / `order_number` / `session_id` / `session_key`; `ref_value` — соответствующий идентификатор. `amount` обязателен и фиксирует максимум, который покупатель может ввести. По умолчанию TTL 30 мин. Отправляет `refund_request.created` (`source: b2b`).
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests`	JWT (панель)	Выпуск токена из модала Issue Refund в панели мерчанта. Та же форма тела, что и у B2B-варианта. По умолчанию TTL 24 ч. Отправляет `refund_request.created` (`source: dashboard`).
`GET`	`/pub/v1/refund-requests/{token}`	Токен в пути	Публичный — checkout-web читает контекст формы (сводку заказа, зафиксированную сумму, текущее эффективное состояние).
`POST`	`/pub/v1/refund-requests/{token}/submit`	Токен в пути	Публичный — покупатель отправляет форму. Тело: `{reason, refund_to_address, amount?, metadata?}`. `amount` опционален — если опущен, используется сумма, зафиксированная мерчантом на ссылке; если указан, сервер проверяет `amount ≤ зафиксированная сумма`. Создаёт строку `Refund`, отправляет `payment.refund.requested`, возвращает `{link_token, refund_id}` для страницы квитанции.
`POST`	`/pub/v1/refund-requests/{token}/request-renewal`	Токен в пути	Публичный — покупатель просит новую ссылку после истечения. Тело: `{customer_note?}`. Отправляет `refund_request.renewal_requested`.
`GET`	`/payment/v1/merchants/{merchant_id}/refund-requests/renewals`	JWT (панель)	Список ожидающих `RENEWAL_REQUESTED` токенов для виджета обновлений мерчанта. Курсорная пагинация.
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests/renewals/{token}/issue-new`	JWT (панель)	Одобрить обновление — выпускает новый `ACTIVE` токен, отзывает старый. Отправляет `refund_request.renewed` + `refund_request.created` (`source: renewal`).
`GET`	`/payment/v1/merchants/{merchant_id}/refund-requests/by-order/{order_id}`	JWT (панель)	Список каждого refund-request токена, когда-либо выпущенного против заказа, с эффективным состоянием. Сначала новые.
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests/{token}/send-email`	JWT (панель)	Поставить в очередь отправку email со ссылкой на refund-request клиенту. Тело: `{to}`. Отправляет `refund_request.email_send_requested`.
`POST`	`/payment/v1/merchants/{merchant_id}/refund-requests/{token}/cancel`	JWT (панель)	Kill-switch мерчанта — переводит `ACTIVE` или `RENEWAL_REQUESTED` → `CANCELED`. Тело: `{reason?}`. Идемпотентно: повторный вызов после того, как статус уже изменился, возвращает успех без повторной отправки. Отправляет `refund_request.canceled` при первом переходе.

Жизненный цикл возврата (после создания)

Применимо к обоим потокам. Endpoint’ы ниже работают со строкой Refund (id начинается с rfn_…), а не с request-токеном.

Метод	Путь	Назначение	Заметки
`GET`	`/b2b/v1/refunds/{id}`	Чтение одного возврата.	Статус: `PENDING` → `APPROVED` → `EXECUTED` \| `REJECTED`.
`GET`	`/b2b/v1/refunds/by-merchant/{merchant_id}`	Список ваших возвратов, курсорная пагинация.	—
`POST`	`/b2b/v1/refunds/{id}/approve`	Одобрить `PENDING` возврат (только для инициированных клиентом — инициированные мерчантом уже в `APPROVED`).	Крипто: переходит в `APPROVED`, далее вызывайте `/submit-tx`.
`POST`	`/b2b/v1/refunds/{id}/reject`	Отклонить `PENDING` возврат.	Отправляет `payment.refund.rejected`.
`POST`	`/b2b/v1/refunds/{id}/submit-tx`	Только крипто — отметить on-chain tx hash, который вы транслировали.	Тело: `{tx_hash, network, token_address}` — все три обязательны.

Каталог (только чтение)

Метод	Путь	Назначение
`GET`	`/v1/supported/networks`	Все сети, на которых InfraIO может проводить расчёт (mainnet + testnet, фильтр по окружению).
`GET`	`/v1/supported/tokens`	Все стейблкоины на этих сетях.
`GET`	`/v1/supported/currencies`	Фиатные валюты, принимаемые для `order.currency`.
`GET`	`/v1/merchants/payment-methods`	Способы, включённые ИМЕННО этим мерчантом — комбинация платформенного каталога + переключателей мерчанта. Используется checkout-web.
`GET`	`/v1/public/merchants/{merchant_id}/branding`	Публичный — что страница checkout читает для оформления.

Health

Метод	Путь	Аутентификация	Назначение
`GET`	`/health`	Нет (публичный)	Простой liveness-зонд — возвращает `{"status":"ok"}`. Это (без префикса `/v1`) — единственный неаутентифицированный health-endpoint — направьте ваши k8s / uptime-мониторы сюда.
`GET`	`/payment/v1/merchants/{merchant_id}/health`	JWT панели	Health конкретного мерчанта — недавняя скорость расчёта intent’ов, backlog sweep. Полезно для собственных status-страниц. Требует session-токен панели, не B2B API-ключ. Доступен только под префиксом `/payment/` gateway — голый путь `/v1/...` публично не роутится.
`GET`	`/payment/v1/stats/health`	JWT панели	Агрегированный health по дереву workspace мерчанта. Не публичный liveness-зонд — сидит за той же JWT-аутентификацией под префиксом `/payment/` gateway.

Курсорная пагинация

Каждый list-endpoint принимает одинаковые query-параметры и возвращает одинаковый конверт. Мы используем непрозрачные курсоры (base64url-кодированные (created_at, id)) вместо offset’ов, чтобы страница не смещалась, когда новая строка появляется в середине прокрутки.

Query-параметр	Тип	По умолчанию	Заметки
`cursor`	`string`	—	Непрозрачный — скопируйте `next_cursor` из предыдущего ответа дословно.
`limit`	`int`	`20`	`1..100`.
`sort_dir`	`'asc' \| 'desc'`	`desc`	Сортировка по `(created_at, id)`.
`from` / `to`	`RFC3339`	—	Опциональный фильтр по временному окну.
`search`	`string`	—	Свободный текстовый фильтр там, где поддерживается.

Конверт ответа:


{
  "orders": [ /* строки страницы */ ],
  "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0...",
  "has_next": true
}

has_next присутствует всегда. next_cursor опускается, когда has_next равен false. Не пытайтесь парсить курсор — его форма внутренняя и будет меняться.

Чего нет на этой странице

Этот индекс покрывает уровень, обращённый к мерчанту — endpoint’ы под /admin/* (инструменты панели, проверка KYB, управление сетями) и внутренние gRPC-маршруты намеренно не перечислены. Спецификация OpenAPI, генерируемая swag, покрывает полный уровень; если она вам нужна, напишите в поддержку, и мы поделимся актуальным снимком.