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

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

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

<a class="md-button md-button--primary" href="../openapi/">Интерактивный справочник</a>
<a class="md-button" href="../openapi/openapi.yaml" download>Скачать openapi.yaml</a>

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

## Создать заявку (СБП или карта) { #createPayment }

<div class="pp-endpoint"><span class="pp-method pp-method--post">POST</span><code><span class="pp-endpoint__base">{{base_url}}</span>/api/v1/payments</code></div>

Создаёт заявку на приём и сразу подбирает реквизиты. Идемпотентна по `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` — см. [Подпись запросов](signing.md).

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

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `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 для этой заявки, публичный хост. Иначе используется адрес проекта. |

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

```json
{
  "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` | Временно недоступна защита от повторов или лимиты — повторите позже |

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

```json
{
  "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"
}
```


## Получить заявку { #getPayment }

<div class="pp-endpoint"><span class="pp-method pp-method--get">GET</span><code><span class="pp-endpoint__base">{{base_url}}</span>/api/v1/payments/{id}</code></div>

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

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

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

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

### Ответы

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

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

```json
{
  "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"
}
```


## Кто я (проверка токена) { #getProject }

<div class="pp-endpoint"><span class="pp-method pp-method--get">GET</span><code><span class="pp-endpoint__base">{{base_url}}</span>/api/v1/project</code></div>

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

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

### Ответы

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