Модульбанк API API

Отрасль: Платежи и финансы. Актуально на 2026-10-13.

API связывает личный кабинет Модульбанка с внешними сервисами. Через него можно получать компании и счета, проверять остатки, выгружать операции, загружать платёжные поручения и принимать уведомления о транзакциях.

Охват

Есть:

Нет — смотри официальную документацию:

Сценарии

Получить счета, баланс и овердрафт

Сценарий возвращает доступные пользователю компании и счета, затем — текущие собственные и заёмные средства выбранного счёта.

  1. Получи токен с правом account-info.
  2. Запроси компании и счета: POST /account-info.
  3. Возьми bankAccounts[].id нужного счёта из ответа и используй его как accountId.
  4. Получи Balance и Overdraft: POST /account-info/balance-details/{accountId}.
curl -X POST 'https://api.modulbank.ru/v1/account-info' \
  -H 'Authorization: Bearer <access_token>'

curl -X POST 'https://api.modulbank.ru/v1/account-info/balance-details/<accountId>' \
  -H 'Authorization: Bearer <access_token>'

Получить историю операций

Метод возвращает операции выбранного счёта с их банковскими статусами. Для последовательной выгрузки учитывай, что состав выборки может меняться между запросами.

  1. Получи токен с правами account-info и operation-history.
  2. Получи bankAccounts[].id через POST /account-info и используй его как accountId.
  3. Запроси операции: POST /operation-history/{accountId}.
  4. Продолжай выборку через фильтры skip и records; обрабатывай возможные повторы и пропуски между страницами.
curl -X POST 'https://api.modulbank.ru/v1/operation-history/<accountId>' \
  -H 'Authorization: Bearer <access_token>' \
  -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 из ответа; платёж будет ожидать подписания.
curl -X POST 'https://api.modulbank.ru/v1/operation-upload' \
  -H 'Authorization: Bearer <access_token>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: <UUID>' \
  -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.
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>'

Вернуть оплату по динамическому 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.
curl -X POST 'https://api.modulbank.ru/v1/sbp/qr-codes/refund' \
  -H 'Authorization: Bearer <access_token>' \
  -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 <access_token>'

Получать уведомления о транзакциях

Модульбанк отправляет 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.
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

Авторизация

Тип: 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

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 да Системный идентификатор счёта

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

{
  "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 нет Альтернативная передача ключа идемпотентности

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

{
  "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

Нюансы

Ошибки

Код Описание
400 { exceptionType: 'AccessDenied', message: 'У пользователя нет доступа к счёту' } для POST /operation-history/{accountId}
503 Сервисные работы: API возвращает этот статус на все виды запросов

Ограничения

Источники

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