Справочник API¶

Все методы API для мерчанта: путь, права, поля запроса, ответы и примеры. Страница собрана из спецификации OpenAPI, поэтому совпадает с тем, что проверяет сервер. Как пройти путь целиком — в быстром старте, что значат статусы и коды — в разделе Статусы и ошибки.

Пути указаны после {{base_url}} — адреса API, выданного вам для песочницы или боевого окружения (см. Окружения).

Интерактивный справочник Скачать openapi.yaml

Временная спецификация

Сейчас здесь основные методы из временной спецификации. Полная спецификация появится из репозитория бэкенда, и эта страница пересоберётся из неё сама.

Создать заявку (СБП или карта)¶

POST{{base_url}}/api/v1/payments

Создаёт заявку на приём и сразу подбирает реквизиты. Идемпотентна по merchant_payment_id: тот же номер с тем же запросом вернёт 200 и сохранённую заявку, тот же номер с другим запросом — 409 payment_idempotency_conflict. 201 может прийти уже со status: error и error_code, если реквизиты не выданы; callback-а о ней не будет. Строгий JSON: неизвестное поле — 400 bad_request. Срок заявки задаёт настройка проекта (по умолчанию 15 минут), в запросе его нет. Подпись обязательна всегда. Таймаут клиента — не меньше 15 секунд.

Доступ: право payments:create · подпись обязательна

Заголовки подписи Signature-Input, Signature, Content-Digest, X-Request-ID, X-Request-Nonce — см. Подпись запросов.

Тело запроса¶

Поле	Тип	Обяз.	Описание
`merchant_payment_id`	string	да	Ваш номер заказа, уникален в проекте; ключ идемпотентности. 1–64 символа `A-Za-z0-9._:-`.
`amount`	number \| string	да	Сумма в основных единицах валюты, больше нуля, до 6 знаков после точки: `3400` или `"3400.50"`. Строка надёжнее числа: без ошибок округления.
`payment_method`	string: `sbp`, `card_transfer`	да	`sbp` — перевод по СБП, `card_transfer` — перевод на карту.
`currency`	string	нет	Код валюты. По умолчанию `RUB`.
`geo_code`	string	нет	Страна, 2 буквы. По умолчанию `RU`.
`bank_code`	string	нет	Банк плательщика — код из справочника (`sber`, `tinkoff`, `ozon`), не БИК. Пусто — любой банк.
`is_intrabank`	boolean	нет	Только перевод внутри одного банка. По умолчанию `false`.
`callback_url`	string, uri	нет	HTTPS-адрес callback для этой заявки, публичный хост. Иначе используется адрес проекта.

Пример запроса

{
  "merchant_payment_id": "order-42",
  "amount": 3400,
  "payment_method": "sbp",
  "bank_code": "sber",
  "callback_url": "https://merchant.example/callbacks"
}

Ответы¶

Код	Что значит
`201`	Заявка создана
`200`	Повтор того же запроса: сохранённая заявка
`400`	Неверный JSON или неизвестное поле (`bad_request`), неверные поля заявки (`invalid_payment`)
`401`	Неверный токен или подпись
`403`	Нет права или доступ закрыт
`409`	Повтор nonce или другой запрос с тем же номером заказа
`413`	Слишком большое тело запроса
`422`	Заявку нельзя провести: нет договора, курса или способ оплаты сейчас недоступен
`429`	Превышен лимит запросов
`500`	Error
`503`	Временно недоступна защита от повторов или лимиты — повторите позже

Пример ответа

{
  "id": "3f1c2b9e-6a8d-4c4b-9a71-2c7f5d1e0a42",
  "merchant_payment_id": "order-42",
  "flow": "runtime_live",
  "status": "processing",
  "amount": 3400,
  "initial_amount": 3400,
  "currency": "RUB",
  "geo_code": "RU",
  "payment_method": "sbp",
  "bank_code": "sber",
  "is_intrabank": false,
  "callback_url": "https://merchant.example/callbacks",
  "is_test": false,
  "merchant_information": {
    "course": 100.0,
    "rate": 11.0,
    "amount_usdt": "34.0000",
    "amount_rate": "3026.0000",
    "amount_usdt_rate": "30.2600"
  },
  "requisite": "+79991234567",
  "holder_name": "Иван Петров",
  "created_at": "2026-09-29T09:30:00Z",
  "updated_at": "2026-09-29T09:30:01Z"
}

Получить заявку¶

GET{{base_url}}/api/v1/payments/{id}

Возвращает заявку в том же виде, что и ответ на создание. Подпись нужна, только если её требует политика проекта.

Доступ: право payments:read · подпись — если её требует политика проекта

Параметры пути¶

Параметр	Тип	Обяз.	Описание
`id`	string, uuid	да	Payment `id` returned on create.

Ответы¶

Код	Что значит
`200`	Заявка
`401`	Неверный токен или подпись
`403`	Нет права или доступ закрыт
`404`	Заявка не найдена, чужая или `id` не UUID
`429`	Превышен лимит запросов

Пример ответа

{
  "id": "3f1c2b9e-6a8d-4c4b-9a71-2c7f5d1e0a42",
  "merchant_payment_id": "order-42",
  "flow": "runtime_live",
  "status": "processing",
  "amount": 3400,
  "initial_amount": 3400,
  "currency": "RUB",
  "geo_code": "RU",
  "payment_method": "sbp",
  "bank_code": "sber",
  "is_intrabank": false,
  "callback_url": "https://merchant.example/callbacks",
  "is_test": false,
  "merchant_information": {
    "course": 100.0,
    "rate": 11.0,
    "amount_usdt": "34.0000",
    "amount_rate": "3026.0000",
    "amount_usdt_rate": "30.2600"
  },
  "requisite": "+79991234567",
  "holder_name": "Иван Петров",
  "created_at": "2026-09-29T09:30:00Z",
  "updated_at": "2026-09-29T09:30:01Z"
}

Кто я (проверка токена)¶

GET{{base_url}}/api/v1/project

Показывает проект и мерчанта, к которым относится токен, и его права. Удобно для первой проверки ключа.

Доступ: подпись — если её требует политика проекта

Ответы¶

Код	Что значит
`200`	Проект токена
`401`	Неверный токен или подпись