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

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

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

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

- [Получить счета, баланс и овердрафт](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/prinyat-oplatu-po-dinamicheskomu-qr-kodu.md)
- [Вернуть оплату по динамическому QR-коду СБП](https://mcp-everything.ru/integrations/modulbank/scenarios/vernut-oplatu-po-dinamicheskomu-qr-kodu.md)

---

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