Модульбанк API: Загрузить платёж на подпись

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

Сценарий создаёт платёжное поручение контрагенту и переводит его в статус InSigning. В ответе приходит системный Id созданной операции.

Получи токен с правами account-info и operation-upload.
Получи номер счёта плательщика: POST /account-info.
Создай платёж: POST /operation-upload с реквизитами, parameters.targetStatus: "InSigning" и уникальным Idempotency-Key.
Сохрани 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"
    }
  }'

Базовые 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

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

Нюансы

Параметры запроса 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://api.modulbank.ru/ Вся интеграция одним документом: https://mcp-everything.ru/integrations/modulbank.md