Сервис MonetaID

Для партнеров — торговых площадок, использующих ЭСП Монета для плательщиков — физических лиц, реализован сервис MonetaID.

MonetaID предназначен для сбора данных физических лиц, в рамках проведения упрощенной или полной идентификации физических лиц, пользователей ЭСП МОНЕТА.РУ. Полная идентификация реализована через провайдеров: T-ID, MobileID, ESIA.

Примеры форм виджета MonetaID. Упрощенная идентификация.

Информацию о доступных способах идентификации необходимо уточнять по адресу коммерческого отдела.

До начала работы партнера (торговой площадки) с сервисом MonetaID должны быть выполнены условия:

• заключен договор ИТВ с НКО МОНЕТА
• созданы личные кабинеты в системе

Схема взаимодействия

Процесс взаимодействия между партнером и MonetaID определяется следующими шагами:

1. Приложение партнера формирует и подписывает запрос, для которого нужно провести идентификацию.
2. Приложение партнера перенаправляет браузер клиента (пользователя ЭСП МОНЕТА.РУ) на специальный адрес, передав токен безопасности.
3. MonetaID запрашивает у клиента партнера (пользователя ЭСП МОНЕТА.РУ) информацию, необходимую для проведения идентификации.
4. MonetaID проводит процедуру идентификации.
5. MonetaID уведомляет приложение партнера о ходе идентификации.
6. MonetaID возвращает клиента (пользователя ЭСП МОНЕТА.РУ) в приложение партнера.

Стенды

Тестовый контур

Для отладки взаимодействия и тестирования в настоящее время доступны следующие окружения:

Под кнопкой “Пройти идентификацию” партнер передает стартовый URL для перенаправления клиентов.
Параметры unitId, phone, cnonce, signature должны вычисляться автоматически на стороне партнера.
cnonce — ограничения: min = 6, max = 32 знака.

Пример стартового URL:

https://<API-root>/identification?subscriberId=<subscriberId>&unitId=<unitId>&phone=<phone>&cnonce=<cnonce>&signature=<signature>

DEMO-режим

Данный режим предполагает подключение и работу с сервисом через https://demo.moneta.ru/login.htm.
Для получения доступов в личные кабинеты demo.moneta.ru необходимо обратиться на адрес mp@payanyway.ru.

Для отладки прохождения упрощенной идентификации (далее УПРИД) в демонстрационном режиме можно использовать любые персональные данные клиента. Проведение идентификации для разных пользователей с одинаковыми паспортными данными невозможно. Чтобы протестировать изменение статуса, необходимо задать одну из “тестовых” фамилий:

Иванов — УПРИД будет пройден успешно.

Петров — УПРИД будет всегда отдавать статус «В процессе».

Попов — УПРИД всегда будет завершаться неудачно.

При указании фамилии Медведев будет осуществлен переход на окно ввода дополнительных данных: ИНН, СНИЛС. ИНН 399474507659 — успешная идентификация.

При указании фамилии Медведев будет осуществлен переход на окно ввода дополнительных данных: ИНН, СНИЛС. ИНН 526317984689 — идентификация всегда будет завершаться неудачно.

Иванов — УПРИД будет пройден успешно.

Петров — УПРИД будет всегда отдавать статус «В процессе».

Попов — УПРИД всегда будет завершаться неудачно.

При указании фамилии Медведев будет осуществлен переход на окно ввода дополнительных данных: ИНН, СНИЛС. ИНН 399474507659 — успешная идентификация.

При указании фамилии Медведев будет осуществлен переход на окно ввода дополнительных данных: ИНН, СНИЛС. ИНН 526317984689 — идентификация всегда будет завершаться неудачно.

Регистрация партнера

Партнеру необходимо предоставить следующие данные на адрес mp@payanyway.ru:

Обязательная информация:

1. Полное и короткое наименование проекта.
2. URL для отправки уведомлений о статусе прохождения идентификации (statusURL).
3. URL для отправки уведомлений о проблемах в работе виджета (notifyURL).

Со стороны MonetaID будет предоставлена следующая информация:

• apiSecret — Код проверки целостности данных. Код, обеспечивающий идентификацию отправителя и возможность проверки целостности данных, известный только системе MonetaID и партнеру. Код будет направлен на адрес электронной почты от Личного кабинета партнера, указанного в Договоре.
• subscribeURL — Специальная ссылка для установления доверия.

Установление доверия

Для проведения идентификации Пользователей ЭСП МОНЕТА.РУ с помощью сервиса MonetaID необходимо пройти процедуру установления доверия с сервисом.
Партнеру необходимо:

1. Войти в Личный кабинет партнера (или demo.moneta.ru для демо-контура).
2. Перейти по ссылке, которую предоставил сервис MonetaID (subscribeURL).
   
3. В появившемся диалоговом окне ознакомиться с информацией о том, какие разрешения партнер предоставит сервису MonetaID.
4. Подтвердить предоставление разрешений:
   

Перечень действий с юнитами/профилями Пользователей ЭСП МОНЕТА.РУ, которые партнер может предоставить сервису MonetaID:

• GetProfileInfo
• FindProfileDocumentFiles
• FindProfileDocuments
• EditProfileDocument
• EditProfile
• ApprovePhoneSendConfirmation
• ApprovePhoneApplyCode
• SimplifiedIdentification

Аутентификация

Предварительные условия

1. Необходимо пройти процедуру регистрации партнера и получить ApiSecret.
2. Необходимо установить доверительные отношения с сервисом MonetaID.

Формирование токена и подписи

Для обновления информации в профиле Пользователя ЭСП МОНЕТА.РУ сервисом MonetaID партнер должен сформировать специальный одноразовый токен.

Для реализации алгоритма формирования единовременного токена использованы следующие стандарты:

1. RFC 3986 Uniform Resource Identifier (URI): Generic Syntax.
2. RFC 2104 HMAC: Keyed-Hashing for Message Authentication.

Токен состоит из 2-х частей:

1. Информационное сообщение, содержащее ключевую информацию о партнере и Пользователе ЭСП МОНЕТА.РУ, служебную информацию.
2. Подпись/Хеш от информационного сообщения из п.1., с использованием заранее полученного общего секрета — ApiSecret.

Формирование информационного сообщения (стартовый URL)

Информационное сообщение состоит из набора ключ-значение, которые закодированы в соответствии с правилами URL-кодирования строк по RFC 3986. Ниже приведен набор обязательных параметров, которые необходимо указать при формировании информационного сообщения (ключи должны следовать в отсортированном порядке, как в таблице ниже):

Формирование подписи

После того как информационное сообщение сформировано, необходимо вычислить подпись/хеш с использованием общего секрета — ApiSecret.

Кодирование ключа производится путем конкатенации в одну строку значений параметров запроса и кода проверки целостности данных, кодированием по алгоритму HMAC-SHA512 и представлением массива байт в виде строки шестнадцатеричных чисел.

Алгоритм формирования:

1. Вычислить HMAC-SHA512 хеш, используя пару (информационное сообщение, секрет).
2. Полученный массив байт перевести в строку в шестнадцатеричном представлении.

// message — значения параметров запроса (в указанном порядке)
// secret — секрет/apiSecret

message = subscriberId + unitId + phone + cnonce + successURL + returnURL + failURL + inprogressURL + targetOrigin + providers
signatureBytes = hmac_sha512(message, secret)
signatureString = bytesToHex(signatureBytes)

После того как подпись в виде hex-строки сформирована, необходимо добавить ее к параметрам запроса с ключом signature. Пример итогового информационного сообщения (стартовый URL):

https://mid.demo.moneta.ru/identification?subscriberId=testSubscriber&unitId=1000&phone=9001234567&cnonce=ygfhkJIBiT3kxjq5P74Tc00Ry6nkC5kK&signature=cf1299778ba5b9310bd2cd42747a43fb79ce72aad16a22704e633900c6dbc9e9a4b61afe53c3fec27c600ef5625a0423b75cc4d96ecaf2890b1dff8db36d4d03

Финальным шагом необходимо использовать полученные параметры при перенаправлении клиента на виджет идентификации.

// БРАУЗЕР КЛИЕНТА
// делаем редирект в браузере клиента на указанный адрес

// DEV окружение
https://mid.demo.moneta.ru/identification?{параметры запроса}

// PROD окружение
https://mid.moneta.ru/identification?{параметры запроса}

Уведомление о статусе идентификации

Результат идентификации будет передан на указанный партнером при регистрации URL в виде GET запроса с query параметрами.

Список передаваемых партнеру параметров:

Проверка signature

Формирование подписи всех переданных параметров происходит через механизм, аналогичный формированию подписи от партнера.
Важно: при проверке валидности входящего вебхука на вашей стороне параметр provider в формировании подписи НЕ УЧАСТВУЕТ.

Таким образом, партнер может убедиться в достоверности вызова, сделав проверку:

// message — информационное сообщение (без provider)
// secret — секрет/apiSecret

message = type + unitId + status + error // error включается, если присутствует
bytesToHex(hmac_sha512(message, secret)) == signature

Код ответа на запрос с уведомлением о статусе идентификации

Для того чтобы сообщить сервису MonetaID, что партнер получил информацию о статусе идентификации, скрипт партнера (statusURL) должен дать ответ с HTTP-кодом 200.
Попытки отправки уведомления будут повторены:

• если сервис MonetaID не смог получить ответ от обработчика;
• если сервер партнера был недоступен.

Работа с iframe в виджете

Тэг iframe может использоваться для отображения виджета идентификации на веб-страницах партнера.

Настройка взаимодействия

Для безопасного обмена данными между iframe виджета и родительской страницей партнера используется HTML5 postMessage API.
Чтобы виджет начал отправлять сообщения, необходимо передать параметр targetOrigin в query-параметрах стартового URL виджета (см. раздел «Формирование информационного сообщения»). Значение этого параметра указывает виджету домен родительской страницы, на который разрешено безопасно отправлять данные. Если параметр не передан, отправка postMessage блокируется в целях безопасности.

Пример отправки сообщения из iframe:

window.top.postMessage(
    JSON.stringify({
       type: "identification_status_change",
       payload: identificationStatus, // например, "SUCCEEDED" или "FAILED"
    }),
    postMessageTarget // берётся из URL-параметра targetOrigin
);

window.top.postMessage(
    JSON.stringify({
       type: "user",
       payload: "delete",
    }),
    targetOrigin
);

Пример обработки сообщения на родительской странице:

window.addEventListener(
    "message",
    (event) => console.log(event.data)
);

Настройка CSP (Content Security Policy)

Взаимодействие виджета MonetaID и ресурсов партнера регулируется политиками безопасности современных браузеров и WebView. Для успешного и безопасного отображения виджета внутри iframe необходимая настройка выполняется на нашей стороне.

В целях защиты от несанкционированного встраивания наш сервер использует HTTP-заголовок Content-Security-Policy: frame-ancestors. По умолчанию виджет блокирует свое отображение на любых сторонних ресурсах.

Что нужно сделать партнеру: Для того чтобы виджет корректно загрузился на вашем сайте, необходимо заранее предоставить нам список доменов (включая тестовые стенды), на которых планируется размещение виджета. Мы добавим ваши домены в наш белый список, и наш сервер начнет отдавать разрешающий заголовок: Content-Security-Policy: frame-ancestors https://ваш-сайт.ру https://test.ваш-сайт.ру