--- slug: "modulbank" name: "Модульбанк API" vendor: "Модульбанк" industry: "finance" docsUrl: "https://api.modulbank.ru/" version: 1 updatedAt: "2026-10-13" --- # Модульбанк API Отрасль: Платежи и финансы. Актуально на 2026-10-13. API связывает личный кабинет Модульбанка с внешними сервисами. Через него можно получать компании и счета, проверять остатки, выгружать операции, загружать платёжные поручения и принимать уведомления о транзакциях. ## Охват Есть: - Компании, счета, текущий баланс и овердрафт - История операций по счёту - Загрузка рублёвого платежа на подпись - Приём и возврат оплаты по динамическому QR-коду СБП - Уведомления о транзакциях и проверка их подписи - Токен из личного кабинета, OAuth 2 и песочница Нет — смотри официальную документацию: - Регистрация торговых точек и кассовые ссылки СБП - Номинальные счета и отчёты по бенефициарам - Импорт платёжных поручений в формате 1С - Подписание платежей квалифицированной электронной подписью ## Сценарии ### Получить счета, баланс и овердрафт Сценарий возвращает доступные пользователю компании и счета, затем — текущие собственные и заёмные средства выбранного счёта. 1. Получи токен с правом `account-info`. 2. Запроси компании и счета: POST /account-info. 3. Возьми `bankAccounts[].id` нужного счёта из ответа и используй его как `accountId`. 4. Получи `Balance` и `Overdraft`: POST /account-info/balance-details/{accountId}. ```bash curl -X POST 'https://api.modulbank.ru/v1/account-info' \ -H 'Authorization: Bearer ' curl -X POST 'https://api.modulbank.ru/v1/account-info/balance-details/' \ -H 'Authorization: Bearer ' ``` ### Получить историю операций Метод возвращает операции выбранного счёта с их банковскими статусами. Для последовательной выгрузки учитывай, что состав выборки может меняться между запросами. 1. Получи токен с правами `account-info` и `operation-history`. 2. Получи `bankAccounts[].id` через POST /account-info и используй его как `accountId`. 3. Запроси операции: POST /operation-history/{accountId}. 4. Продолжай выборку через фильтры `skip` и `records`; обрабатывай возможные повторы и пропуски между страницами. ```bash curl -X POST 'https://api.modulbank.ru/v1/operation-history/' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "skip": 0, "records": 50 }' ``` ### Загрузить платёж на подпись Сценарий создаёт платёжное поручение контрагенту и переводит его в статус `InSigning`. В ответе приходит системный `Id` созданной операции. 1. Получи токен с правами `account-info` и `operation-upload`. 2. Получи номер счёта плательщика: POST /account-info. 3. Создай платёж: POST /operation-upload с реквизитами, `parameters.targetStatus: "InSigning"` и уникальным `Idempotency-Key`. 4. Сохрани `Id` из ответа; платёж будет ожидать подписания. ```bash curl -X POST 'https://api.modulbank.ru/v1/operation-upload' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: ' \ -d '{ "payment": { "Number": "12345", "Date": "15.08.2023", "Sum": 1.01, "PayerAccount": "40802810870010433949", "RecipientName": "ООО Ромашка", "RecipientINN": "1242610857", "RecipientKPP": "256845746", "RecipientAccount": "40702810870010408317", "RecipientBankBik": "044525092", "RecipientBankCorrAccount": "30101810645250000092", "PaymentPurpose": "Оплата поставщику Без НДС", "TypeIndicator": "0" }, "parameters": { "targetStatus": "InSigning" } }' ``` ### Принять оплату по динамическому QR-коду СБП Сценарий создаёт 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 ' curl -X POST 'https://api.modulbank.ru/v1/sbp/qr-codes/dynamic' \ -H 'Authorization: Bearer ' \ -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 ' ``` ### Вернуть оплату по динамическому QR-коду СБП Возврат создаётся по номеру исходной операции СБП. Метод возвращает `requestId`, по которому запрашивается итоговый статус. 1. Получи токен с правами `account-info` и `operation-upload`. 2. Запроси GET /sbp/qr-codes/{qrcId} и возьми `operationId` успешной оплаты для передачи как `sbpOperId`. 3. Создай полный или частичный возврат: POST /sbp/qr-codes/refund. 4. Возьми `requestId` из ответа и передай его как `refundId` в GET /sbp/qr-codes/refund/{refundId}. 5. Проверь `status` возврата; пример завершённого статуса в документации — `Executed`. ```bash curl -X POST 'https://api.modulbank.ru/v1/sbp/qr-codes/refund' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "sbpOperId": "A931608381015300KXVWKp1837BE5609", "type": "full", "remitInfo": "" }' curl -X GET 'https://api.modulbank.ru/v1/sbp/qr-codes/refund/13a8804e-ded0-4f29-a231-725ffce47859' \ -H 'Authorization: Bearer ' ``` ### Получать уведомления о транзакциях Модульбанк отправляет HTTPS-запрос на зарегистрированный адрес приложения. Получатель проверяет `SHA1Hash` и подтверждает доставку ответом HTTP 200. 1. Получи токен с правом `operation-history`. 2. Укажи HTTPS-адрес для уведомлений при регистрации приложения; для токена из личного кабинета настрой его в «Настройки» → «Услуги» → «API Банка» → «Генерация токена авторизации». 3. Прими входящий POST /modulbank с JSON-объектом операции. 4. Для токена из личного кабинета вычисли SHA-1 от строки `<первые 10 символов токена авторизации>&operationId`; для OAuth — от `clientSecret&operationId`. Сравни HEX-результат с `SHA1Hash`. 5. После успешной обработки верни HTTP 200. ```http POST /modulbank HTTP/1.1 Host: example.ru Content-Type: application/json { "companyInn": "1111111111", "companyKpp": "", "operation": { "id": "a4b825ca-a6f8-4996-a1db-a5f3028bb68d", "companyId": "599ebe36-ed20-49c4-b802-a5ec0329ebce", "status": "Received", "category": "Debet", "contragentName": "Индивидуальный предприниматель Иванов Иван Иванович", "contragentInn": "1111111111", "contragentKpp": "", "contragentBankAccountNumber": "30101810000000000005", "contragentBankName": "МОСКОВСКИЙ ФИЛИАЛ ОАО КБ \"РЕГИОНАЛЬНЫЙ КРЕДИТ", "contragentBankBic": "044583340", "currency": "RUR", "amount": 100000.0, "bankAccountNumber": "30101810000000000001", "paymentPurpose": "Оплата по счету №4 от 01.04.2016 г. Без НДС", "executed": "2016-04-01T00:00:00", "created": "2016-04-01T00:00:00", "docNumber": "4", "kbk": "", "oktmo": "", "paymentBasis": "", "taxCode": "", "taxDocNum": "", "taxDocDate": "", "payerStatus": "", "uin": "", "absId": "34323454545455", "ibsoId": "1332345565654", "cardId": "4bdd2fc0-584d-41d8-9241-3f074480fe52" }, "SHA1Hash": "b2ee4a9197f4a90e893caa4f62eeba0b579321f8" } ``` ## Базовые URL - Боевой: `https://api.modulbank.ru/v1/` - Песочница: `https://api.modulbank.ru/v1/` ## Авторизация Тип: Bearer-токен Для работы только со своей учётной записью сгенерируй токен в личном кабинете через пункт «Подключиться к API». Передавай его в каждом запросе в заголовке `Authorization: Bearer ` и не передавай третьим лицам. Для приложения других пользователей зарегистрируй приложение через `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 ### POST /account-info/balance-details/{accountId} — Получение баланса и овердрафта по счету Возвращает `Balance` и `Overdraft` выбранного счёта. Требуется право `account-info`. Документация: https://api.modulbank.ru/#tag/Poluchenie-dannykh/paths/~1account-info~1balance-details~1%7BaccountId%7D/post | Параметр | Где | Тип | Обяз. | Описание | |---|---|---|---|---| | `accountId` | path | string | да | Системный идентификатор счёта | Пример ответа: ```json { "Balance": 0, "Overdraft": 0 } ``` ### POST /operation-history/{accountId} — Просмотр истории операций Возвращает операции счёта. Требуется право `operation-history`; операции сортируются по дате проведения или изменения по убыванию, затем по идентификатору по возрастанию. Документация: https://api.modulbank.ru/#tag/Poluchenie-dannykh/paths/~1operation-history~1%7BaccountId%7D/post | Параметр | Где | Тип | Обяз. | Описание | |---|---|---|---|---| | `accountId` | path | string | да | Системный идентификатор счёта | | `statuses` | body | array | нет | Статусы возвращаемых операций | | `SbpRetailPointId` | body | string | нет | Идентификатор торговой точки СБП | | `operations` | body | array | нет | Идентификаторы транзакций | | `AbsIds` | body | array | нет | Идентификаторы АБС транзакций | | `category` | body | string | нет | Направление: Debet — входящий, Credit — исходящий | | `from` | body | string | нет | Начало периода, формат yyyy-MM-dd | | `till` | body | string | нет | Конец периода, формат yyyy-MM-dd | | `skip` | body | integer | нет | Число пропускаемых строк, по умолчанию 0 | | `records` | body | integer | нет | Число записей от 0 до 50, по умолчанию 10 | ### POST /operation-upload — Импорт платежей в формате JSON Создаёт платёжное поручение из JSON. Без `parameters.targetStatus` платёж остаётся черновиком; значение `InSigning` переводит его на подпись. Требуется право `operation-upload`. Документация: https://api.modulbank.ru/#tag/Zagruzka-dannykh/paths/~1operation-upload/post | Параметр | Где | Тип | Обяз. | Описание | |---|---|---|---|---| | `Idempotency-Key` | header | string | нет | Ключ идемпотентности: до 256 символов, латиница, цифры и дефис | | `idempotency-key` | query | string | нет | Альтернативная передача ключа идемпотентности | Пример ответа: ```json { "Id": "38a5a5bb-dc30-49a2-b175-1de0d1488c43", "Error": "string" } ``` ### 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-кода | ### POST /sbp/qr-codes/refund — Возврат по платежу Создаёт возврат по `sbpOperId`. `type` принимает `full` или `partial`; `amount` передаёт сумму частичного возврата, `remitInfo` — причину длиной до 140 символов. Документация: https://api.modulbank.ru/#tag/QR-Pay/paths/~1sbp~1qr-codes~1refund/post ### GET /sbp/qr-codes/refund/{refundId} — Статус возврата Возвращает исходную операцию СБП, операцию возврата, сумму и статус. Документация: https://api.modulbank.ru/#tag/QR-Pay/paths/~1sbp~1qr-codes~1refund~1%7BrefundId%7D/get | Параметр | Где | Тип | Обяз. | Описание | |---|---|---|---|---| | `refundId` | path | string | да | ID возврата | ### POST /modulbank — Уведомление о произошедшей транзакции Входящий запрос на зарегистрированный приложением URI. Тело содержит `companyInn`, `companyKpp`, объект `operation` и подпись `SHA1Hash`; приложение должно ответить HTTP 200. Документация: https://api.modulbank.ru/#tag/Uvedomleniya-o-proizoshedshikh-tranzaktsiyakh-veb-khuki ## Нюансы - Параметры запроса 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 в песочнице недоступен. - Даты проведения и создания платежа указываются по московскому времени. ## Ошибки | Код | Описание | |---|---| | `400` | { exceptionType: 'AccessDenied', message: 'У пользователя нет доступа к счёту' } для POST /operation-history/{accountId} | | `503` | Сервисные работы: API возвращает этот статус на все виды запросов | ## Ограничения - Временный OAuth-код действует меньше 1 минуты и используется один раз. `accessToken` действует 3 года, после чего автоматически аннулируется. - POST /operation-history/{accountId} возвращает не более 50 записей за запрос; значение `records` по умолчанию — 10, `skip` — 0. - `Idempotency-Key` не может быть пустым и содержит не более 256 символов: латиницу, цифры и дефис. - Если приложение не подтвердило вебхук HTTP 200, Модульбанк делает ещё две попытки: через 10 минут и через час. - `lifetime` динамического QR-кода задаётся в минутах: от 5 до 129600, по умолчанию 12. Методы QR Pay недоступны в песочнице; документация рекомендует тестировать на бою малыми суммами. ## Источники - [Интеграция с Модульбанком по API](https://api.modulbank.ru/) - [OpenAPI specification](https://api.modulbank.ru/v1/swagger/docs/v1) - [Получение данных](https://api.modulbank.ru/#tag/Poluchenie-dannykh) - [Загрузка данных](https://api.modulbank.ru/#tag/Zagruzka-dannykh) - [QR Pay](https://api.modulbank.ru/#tag/QR-Pay) --- Если этого недостаточно — официальная документация: https://api.modulbank.ru/ JSON: https://mcp-everything.ru/api/integrations/modulbank. MCP: https://mcp-everything.ru/mcp