1. В личном кабинете банка в меню "+" выберите "Интеграция с банком"


2. Сгенерируйте токен и воспользуйтесь описанием API

Получить токен авторизации можно двумя способами: сгенерировать его в ЛК Модульбанка или получить по протоколу OAuth 2.

Генерация токена в ЛК

Если вы хотите получать от API данные исключительно по свой учетной записи в Модульбанке, воспользуйтесь механизмом получения токена в Личном кабинете. Выберите пункт «Подключиться к API» в меню действий ЛК и следуйте дальнейшим инструкциям.

Важно!Полученный токен привязан к вашей учетной записи в ЛК и не должен передаваться третьим лицам!

После генерации токена вы можете сразу начать его использование для получения данных в API.

OAuth 2. Общая схема работы

Если вы разрабатываете приложение (бот для телеграма, плагин для общедоступной CRM и т.д.), которое может быть полезно для любого пользователя Модульбанка, вы можете авторизовывать пользователей через сервер авторизации Модульбанка по OAuth подобному протоколу. Схема авторизации пользователей идентична протоколу OAuth 2.0, за небольшим исключением что сервер авторизации Модульбанка кроме формата x-www-form-urlencoded также поддерживает формат json в теле запроса. Для того чтобы стороннее приложение могло совершать запросы к API от лица конкретного пользователя, приложению необходимо получить токен авторизации, подтверждающий что пользователь предоставил приложению права на выполнение тех или иных действий.

Важно!Если вы хотите авторизовывать пользователей Модульбанка по протоколу OAuth, ваше приложение должно быть зарегистрировано у нас. Для регистрации приложения напишите нам письмо на api@modulbank.ru. В ответ мы вышлем вам clientId и clientSecret — уникальные для каждого приложения идентификатор и секретное слово (необходимые параметры для взаимодействия с сервером авторизации Модульбанка).

Схема получения токена авторизации пользователя сторонним приложением.

1. Пользователь инициирует авторизацию стороннего приложения.


2. Приложение отправляет запрос Authorization Request на сервер авторизации Модульбанка.


3. Сервер авторизации Модульбанка перенаправляет пользователя на страницу авторизации.


4. Пользователь вводит свой логин и пароль, просматривает список запрашиваемых прав и подтверждает, либо отклоняет запрос авторизации.


5. Приложение получает ответ Authorization Response в виде HTTP Redirect со временным токеном для получения доступа или кодом ошибки.


6. Приложение, используя полученный временный токен доступа, отправляет запрос на получение токена авторизации.


7. Ответ содержит токен авторизации (access_token).

Методы для получения информации по счетам и операциям.

Описание
При появлении новой исполненной транзакции в Модульбанке, вашему приложению будет отправлено уведомление. Уведомление — это http запрос, выполненный на специальный, указанный при регистрации приложения Uri для уведомлений.

Требуемые права токена
operation-history

Пример
При регистрации в качестве Uri для уведомлений был указан адрес https://example.ru/modulbank/. Стороннее приложение авторизовало пользователя, работающего в ИП Иванов Иван Иванович. При появлении новой исполненной транзакции по счету открытому ИП Иванов Иван Иванович, Модульбанк выполнит следующий POST запрос:
POST /modulbank
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"
}


Важно! Все уведомления отправляются исключительно по протоколу HTTPS

В теле запроса передается информация о произошедшей транзакции в виде JSON объекта.

Описание полей объекта:

1. Сформировать строку из параметров уведомления в кодировке UTF-8.
   Формат строки:
   <первые 10 символов токена авторизации>&operationId
   Пример строки параметров для токена NDIWJFNASDJKFHNASDJFASDJKFHASDJKFHASDJFHASDK:
   NDIWJFNASD&a4b825ca-a6f8-4996-a1db-a5f3028bb68d


2. Вычислить значение хэш-функции SHA-1 от полученной строки.


3. Отформатировать полученный результат в HEX-кодированном виде.
   Пример рассчитанного значения параметра sha1_hash для примера:
   27063efdefd944907e08cfa242170f4d1a260c36

1. Сформировать строку из параметров уведомления в кодировке UTF-8 (где clientSecret — это секретное слово приложения).
   Формат строки:
   clientSecret&operationId
   Пример строки параметров:
   JSADFJASFJASLKJWERMNGIODVBKLMNEWSTOHEJLWRTFNEHNSDJLFHNWEO&a4b825ca-a6f8-4996-a1db-a5f3028bb68d


2. Вычислить значение хэш-функции SHA-1 от полученной строки.


3. Отформатировать полученный результат в HEX-кодированном виде.
   Пример рассчитанного значения параметра sha1_hash для примера:
   f232c33785c13009614a7ddb69f12133300a33c8

Методы по созданию и подписанию платежей.

Идемпотентность платежей

1. Ключ идемпотентности опционален к заполнению, можно указывать в запросе в виде query-параметра, например: https://api.modulbank.ru/v1/operation-upload?idempotency-key=<UUID> или в header-параметрах: Idempotency-Key <UUID>


2. Валидации: при указании ключ идемпотентности не должен быть пустым, может содержать до 256 символов - латиница, цифры, дефис


3. При получении запроса operation-upload с Idempotency-Key, сервис проверит, была ли ранее создана операция с таким UUID. Если операция была создана, сервер вернет ответ с текущим Id этой операции. Если операции с таким UUID не найдено, сервис начнет ее выполнение

API QR Pay (PortalAPI/SBP)

Режим песочницы недоступен для методов QR Pay. Рекомендуется проводить тестирование на бою малыми суммами. По динамическим QR-кодам возможен возврат платежа.

Базовый адрес
https://api.modulbank.ru/v1/

Авторизация
Смотрите раздел получение данных

Требуемые права токена
account-info, operation-upload

Типы перечислений

Тип ТСП

Владелец номинального счета ежедневно не позднее 23:00 МСК отправляет данные бенефициарных владельцев (бенефициаров). Для этого используется публичное API Модульбанка. В массиве данных должна содержаться информация обо всех бенефициарах, чьи деньги находятся на номинальном счете на момент отправки массива, а также о бенефициарах, по которым были движения средств за прошедшие сутки.

Система Модульбанка обрабатывает полученные данные, и на их основе формирует Отчет о бенефициарных владельцах на текущую дату и Анкеты бенефициарных владельцев по форме, которая соответствует требованиям 115-ФЗ. Если клиент не прислал массив, то мы отправляем в его личный кабинет уведомление о том, что данные нужно отправить.

Отчет и Анкеты размещаются в личном кабинете Модульбанка владельца номинального счета. Туда же отправляется уведомление о необходимости подписания файлов.

Владелец номинального счета на следующий день после отправки массива подписывает Отчёт и Анкеты. Это делается или через личный кабинет или через API Модульбанка. В первом случае владелец входит в кабинет и подписывает Отчет простой электронной подписью, а Анкеты - усиленной квалифицированной электронной подписью (УКЭП). Способ подписания через API описан ниже.

Подписанные отчет и анкеты сохраняются в системе Модульбанка.

Подписание Отчёта по бенефициарам через API

Здесь и ниже: при получении ошибок попытайтесь выполнить рекомендации из сообщения об ошибке. Если это не поможет - напишите в поддержку банка.

Есть два метода подписания отчетов по бенефициарам: v1 и v2.
Метод v2 реализован позже и отличается тем, что сначала нужно получить и подписать PDF всех ранее неподписанных отчётов, а не только последнего. На текущий момент работают обе версии, но мы настоятельно рекомендуем использовать метод v2, так как в скором времени v1 будет отключён.

Описание метода v1:
1. По номеру номинального счёта получите PDF с последним отчётом о бенефициарах – метод "Получить файл отчёта".
2. Полученный отчёт подпишите с помощью УКЭП и передайте в банк отсоединённую подпись в формате Base64 – метод "Проверить и передать в банк подписанный отчёт".

Описание метода v2:
1. По номеру номинального счёта получите список всех ID отчетов, которые ранее не были подписаны – "Метод получения информации о не подписанных отчетов".
2. По полученным ID с помощью "Метода получения файла отчета" получите PDF файлы отчетов.
3. Полученные файлы подпишите с помощью УКЭП и передайте в банк отсоединённую подпись в формате Base64 – метод "Проверить и передать в банк подписанный отчёт".

Пример того, как можно подписать данные см. ниже.

Подписание Анкет бенефициаров через API

1. Методом "Получить список анкет по бенефициарам" получите id частей анкет (Guid). В случае, когда бенефициаров немного, каждая анкета будет иметь одну часть, но возможно и большее количество.
2. Вызовите метод "Получить файл с частью конкретной анкеты" для получения zip-архива.
3. Используйте метод "Проверить и передать в банк подписанную часть анкеты" для загрузки отсоединённой подписи в формате Base64. Пример того как можно подписать данные см. ниже.

Подписание строки и получение отсоединённой электронной подписи в формате Base64.

Скачать приложение cryptcp от компании КриптоПро и выполнить запрос:

cryptcp.x64.exe -sign -f <путь к файлу хранилищу сертификатов ЭЦП> -dn "<(при необходимости) строка для поиска сертификата, например ИНН компании>" -detached -pin <пароль> <путь к подписываемому файлу>

Например:
cryptcp.x64.exe -sign -f cert2.cer -dn "7840473679" -detached -pin password123 test.txt

Безопасно ли использование API, ведь с его помощью можно получить данные, чтобы воспользоваться деньгами клиентов?
Интеграции партнеров с Модульбанком безопасны и основаны на протоколе OAuth2, признанном во всем мире.
При подключении интеграции вы сами подтверждаете уровень доступа, для учетных систем это, как правило, account-info + operation-history. С таким уровнем доступа невозможно инициировать движение средств, даже если злоумышленник каким-то образом узнает токен доступа.

Сколько стоит подключиться к АПИ?
Бесплатно. Подключение доступно на всех тарифах

Как генерируются clientid и clientsecret?
Нужно написать запрос на почту api@modulbank.ru, наша служба поддержки сгенерирует ключи

Есть ли у вас тестовые ключи для подключения api?
Есть режим "песочница", некоторые методы API можно протестировать в нем. Тестовых аккаунтов в продуктивной среде нет

Меняется ли access token? Если два раза пройти аутентификацию, вернется один и тот же access token?
Токен выдается на 3 года и не меняется в течение этого времени. Его можно отозвать по апи

Возможна ли интеграция по API для Android и Ios приложений?
Да, методы Public API можно вызывать из мобильных приложений

Есть ли список хостов (IP или домены) для веб-хуков, с которых нужно разрешить принимать запросы в фаерволе?
185.137.76.36
185.137.76.37
185.137.76.38
185.137.76.39

Куда нужно прописать адрес для исходящего веб-хука?
Адрес вебхука прописывается в ЛК клиента Настройки -> Услуги -> API Банка -> Генерация токена авторизации

Можно ли протестировать уведомления о произошедших транзакциях (веб-хуки) в режиме песочницы?
Такой возможности нет

Какие сообщения передаются в веб-хуках? Была операция, но веб-хук по ней не пришел
Мы отправляем веб-хуки для платежей в следующих статусах:
Draft (Черновик), SendToBank (Ожидающая исполнения), Executed (Исполненная), RejectByBank (Отказано банком в исполнении), Canceled (Отменённая), Received (Исполненная), PayReceived (Исполненная (Оплачено)), ClarifyRequiredOutcome (Требует уточнения)

Что делать, если не приходят/перестали приходить оповещения о платежах через веб-хуки?

1. Проверить, не просрочен ли токен


2. Разрешить принимать запросы в фаерволе с адресов
   185.137.76.36
   185.137.76.37
   185.137.76.38
   185.137.76.39


3. Написать на почту api@modulbank.ru или в чат банка