# Модульбанк API: Принять оплату по динамическому QR-коду СБП

Сценарий из mcp-everything. Актуально на 2026-10-13.

Сценарий создаёт QR-код на заданную сумму для зарегистрированной торговой точки. Оплата считается успешной, когда статус QR-кода становится `Accepted`.

1. Получи токен с правами `account-info` и `operation-upload`.
2. Получи `companyId`: POST /account-info.
3. Запроси точки: GET /sbp/retail-points с `companyId` и выбери зарегистрированную точку.
4. Создай код: POST /sbp/qr-codes/dynamic с `retailPointId`, суммой и назначением.
5. Передай покупателю `payload` из ответа и сохрани `qrcId`.
6. Проверяй GET /sbp/qr-codes/{qrcId}, пока `status` не станет `Accepted`, `Rejected` или `TimedOut`.

```bash
curl -X GET 'https://api.modulbank.ru/v1/sbp/retail-points?companyId=599ebe36-ed20-49c4-b802-a5ec0329ebce' \
  -H 'Authorization: Bearer <access_token>'

curl -X POST 'https://api.modulbank.ru/v1/sbp/qr-codes/dynamic' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "retailPointId": "a604633b-f067-4be3-ab53-6bf9114d689f",
    "sum": 500,
    "extraInfo": "Чёрный кофе",
    "lifetime": 12
  }'

curl -X GET 'https://api.modulbank.ru/v1/sbp/qr-codes/AS1000670LSS7DN18SJQDNP4B05KLJL3' \
  -H 'Authorization: Bearer <access_token>'
```

## Базовые URL

- Боевой: `https://api.modulbank.ru/v1/`
- Песочница: `https://api.modulbank.ru/v1/`

## Авторизация

Тип: Bearer-токен

Для работы только со своей учётной записью сгенерируй токен в личном кабинете через пункт «Подключиться к API». Передавай его в каждом запросе в заголовке `Authorization: Bearer <access_token>` и не передавай третьим лицам.

Для приложения других пользователей зарегистрируй приложение через `api@modulbank.ru` и получи `clientId` и `clientSecret`. Отправь пользователя на GET /oauth/authorize с `clientId`, `redirectUri`, `scope` и `state`, затем немедленно обменяй одноразовый `code` через POST /oauth/token. Доступные права `scope`: `account-info`, `operation-history`, `operation-upload`.

В песочнице используй `clientId: sandboxapp`, `clientSecret: sandboxappsecret` и `Authorization: Bearer sandboxtoken`; реальные идентификаторы и токены там запрещены.

## Методы сценария

### POST /account-info — Получение информации о компаниях пользователя

Возвращает компании пользователя и их банковские счета. Системный идентификатор счёта находится в `bankAccounts[].id`, номер — в `bankAccounts[].number`; требуется право `account-info`.

Документация: https://api.modulbank.ru/#tag/Poluchenie-dannykh/paths/~1account-info/post

### GET /sbp/retail-points — Получение списка точек продаж

Возвращает точки продаж, зарегистрированные в СБП. Для QR Pay требуются права `account-info`, `operation-upload`.

Документация: https://api.modulbank.ru/#tag/QR-Pay/paths/~1sbp~1retail-points/get

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `companyId` | query | string<uuid> | нет | ID компании из POST /account-info |

### POST /sbp/qr-codes/dynamic — Создание нового динамического QR-кода

Создаёт QR-код для конкретной торговой точки. Ответ содержит `qrcId` и `payload`; `extraInfo` обязательно и ограничено 140 символами.

Документация: https://api.modulbank.ru/#tag/QR-Pay/paths/~1sbp~1qr-codes~1dynamic/post

### GET /sbp/qr-codes/{qrcId} — Получение данных QR-кода

Возвращает свойства и статус QR-кода: `NotStarted`, `Received`, `InProgress`, `Accepted`, `Rejected` или `TimedOut`.

Документация: https://api.modulbank.ru/#tag/QR-Pay/paths/~1sbp~1qr-codes~1%7BqrcId%7D/get

| Параметр | Где | Тип | Обяз. | Описание |
|---|---|---|---|---|
| `qrcId` | path | string | да | ID QR-кода |

## Нюансы

- Параметры запроса API передаются в теле; поддерживаются `application/json` и `x-www-form-urlencoded`. Все сетевые взаимодействия должны идти по HTTPS с проверкой SSL-сертификата.
- В истории новая операция не обязательно появляется в начале. Если данные меняются между запросами, пагинация через `skip` и `records` может дать повторы или пропуски.
- В поле вебхука `operation.category` документация задаёт `Debet` для входящей и `Credit` для исходящей операции. Не подменяй эти значения привычной банковской трактовкой.
- Вебхуки отправляются только по HTTPS. Тестировать их в песочнице нельзя.
- Если вебхуки не приходят, разреши в фаерволе адреса `185.137.76.36`, `185.137.76.37`, `185.137.76.38`, `185.137.76.39` и проверь срок токена.
- Ключ идемпотентности для POST /operation-upload необязателен, но при повторе с тем же UUID сервер возвращает текущий `Id` ранее созданной операции.
- Если `parameters.targetStatus` не передан в POST /operation-upload, платёж создаётся как черновик.
- В песочнице реальные данные и идентификаторы запрещены. Для POST /operation-history/{accountId} там работают только фильтры `records` и `skip`; QR Pay в песочнице недоступен.
- Даты проведения и создания платежа указываются по московскому времени.

## Другие сценарии

- [Получить счета, баланс и овердрафт](https://mcp-everything.ru/integrations/modulbank/scenarios/poluchit-scheta-balans-i-overdraft.md)
- [Получить историю операций](https://mcp-everything.ru/integrations/modulbank/scenarios/poluchit-istoriyu-operatsiy.md)
- [Загрузить платёж на подпись](https://mcp-everything.ru/integrations/modulbank/scenarios/zagruzit-platezh-na-podpis.md)
- [Вернуть оплату по динамическому QR-коду СБП](https://mcp-everything.ru/integrations/modulbank/scenarios/vernut-oplatu-po-dinamicheskomu-qr-kodu.md)
- [Получать уведомления о транзакциях](https://mcp-everything.ru/integrations/modulbank/scenarios/poluchat-uvedomleniya-o-tranzaktsiyah.md)

---

Если этого недостаточно — официальная документация: https://api.modulbank.ru/
Вся интеграция одним документом: https://mcp-everything.ru/integrations/modulbank.md