Модульбанк 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.

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	нет	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 в песочнице недоступен.
• Даты проведения и создания платежа указываются по московскому времени.

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

• Получить счета, баланс и овердрафт
• Получить историю операций
• Загрузить платёж на подпись
• Вернуть оплату по динамическому QR-коду СБП
• Получать уведомления о транзакциях

---

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