<div class="pp-hero" markdown>
<p class="pp-eyebrow">Платёжный API · v1</p>

# Принимайте оплату по СБП и по карте через один API

Вы создаёте заявку — API выдаёт реквизиты для перевода, следит за оплатой
и присылает подписанный callback, когда деньги пришли.

[Быстрый старт за 15 минут](quickstart.md){ .md-button .md-button--primary }
[Подпись запросов](signing.md){ .md-button }
</div>

## Интеграция за пять шагов { #five-steps }

<ol class="pp-steps">
<li><strong>Проект и токен</strong>Создайте проект в кабинете и выпустите токен API.</li>
<li><strong>Ключ подписи</strong>Сгенерируйте ключ Ed25519 и загрузите публичную часть в кабинет.</li>
<li><strong>Callback</strong>Укажите адрес для уведомлений и выпустите секрет подписи.</li>
<li><strong>Заявка</strong>Создайте подписанный <code>POST /api/v1/payments</code> и покажите плательщику реквизиты.</li>
<li><strong>Результат</strong>Примите callback, проверьте подпись и отметьте заказ оплаченным.</li>
</ol>

<div class="pp-seq" data-lanes="Ваш сервер|API|Плательщик" markdown>

1. **Ваш сервер → API.** `POST /api/v1/payments`, подпись Ed25519
2. **API ⇢ Ваш сервер.** `201`: `status=processing`, реквизиты, получатель и банк
3. **Ваш сервер → Плательщик.** Показываете реквизиты, сумму и срок оплаты
4. **Плательщик.** Переводит по СБП или на карту в приложении своего банка
5. **API → Ваш сервер.** Callback `status=completed`, подпись HMAC-SHA256
6. **Ваш сервер ⇢ API.** Отвечаете `2xx`

</div>

## Что читать дальше { #next }

<div class="grid cards pp-bento" markdown>

-   :material-lightning-bolt:{ .lg } **[Приём по СБП](sbp.md)**

    ---

    Заявка, реквизиты для плательщика, статусы, опрос и крайние случаи.

-   :material-credit-card-outline:{ .lg } **[Приём по карте](card.md)**

    ---

    Перевод на карту: чем отличается от СБП и что показать плательщику.

-   :material-signature-freehand:{ .lg } **[Подпись запросов](signing.md)**

    ---

    RFC 9421 и Ed25519: готовые функции и проверочный пример.

-   :material-bell-ring-outline:{ .lg } **[Callback-и](callbacks.md)**

    ---

    Уведомления о результате и проверка HMAC-подписи.

-   :material-alert-circle-outline:{ .lg } **[Статусы и ошибки](statuses.md)**

    ---

    Все статусы, коды ошибок и когда повторять запрос.

-   :material-robot-outline:{ .lg } **[Для ИИ-агентов](ai-agents.md)**

    ---

    llms.txt, Markdown-версии страниц и MCP-сервер документации.

</div>

## Окружения { #environments }

Адреса в документации записаны обозначениями — вместо них подставьте свои значения:

- `{{base_url}}` — адрес API, который вам выдают при подключении. У песочницы и боевого
  окружения он свой. В примерах запросов `{{base_url}}` стоит перед путём:
  `POST {{base_url}}/api/v1/payments`.
- `{{cabinet_url}}` — адрес кабинета мерчанта. Его сообщают вместе с доступом.

| Окружение | Адрес API | Кабинет | Префикс токена |
| --- | --- | --- | --- |
| Песочница | `{{base_url}}` песочницы | `{{cabinet_url}}` песочницы | `nl_test_` |
| Боевое | `{{base_url}}` боевого окружения | `{{cabinet_url}}` боевого окружения | `nl_live_` |

Держите `{{base_url}}` в настройке приложения, а не в коде: при переходе в бой поменяется
только она.

Песочница работает так же, как боевое окружение: те же подпись, лимиты и ошибки.
Отличается только то, что деньги не двигаются. Подробнее — в разделе [Песочница](sandbox.md).

## Общие правила API { #conventions }

- **Формат.** Запросы и ответы — JSON в UTF-8. Сервер разбирает тело строго:
  неизвестное поле или лишний текст после объекта — `400 bad_request`.
- **Доступ.** В каждом запросе заголовок `Authorization: Bearer <токен проекта>`.
- **Подпись.** Каждый изменяющий запрос подписан ключом Ed25519 по
  [RFC 9421](signing.md). Без подписи заявку создать нельзя — ни в песочнице, ни в бою.
- **Суммы.** `amount` — в основных единицах валюты: `3400` или `"3400.50"` рублей. Суммы
  в USDT в расчёте `merchant_information` — десятичные строки: `"34.0000"`; курс `course`
  и ставка `rate` — числа с двумя знаками: `100.00`.
- **Время.** Все даты — RFC 3339 в UTC, например `2026-09-28T12:00:00Z`.
- **Ошибки.** Тело ошибки — `{"error":"<код>"}`. Список кодов —
  в разделе [Статусы и ошибки](statuses.md).
- **Трассировка.** Заголовок `X-Request-ID` из запроса возвращается в ответе.
  Сохраняйте его в логах: по нему поддержка найдёт ваш запрос.

## Методы API { #endpoints }

| Метод | Что делает | Подпись |
| --- | --- | --- |
| `POST /api/v1/payments` | Создаёт заявку на приём | всегда |
| `GET /api/v1/payments/{id}` | Возвращает заявку по `id` | если включена в политике проекта |
| `GET /api/v1/project` | Показывает проект и права токена | если включена в политике проекта |

Полное описание полей — в [API reference](api-reference.md).