Callback / PostMessage

Назначение

Страница описывает два способа узнать, что пользователь завершил сценарий KYC: фронтовое событие PostMessage для iframe/WebSDK и серверный HTTP callback для backend-интеграции.

PostMessage помогает быстро обновить интерфейс пользователя, а callback нужен для надежной серверной обработки результата.

PostMessage

Интерфейс PostMessage позволяет оперативно получить информацию об окончании этапа сбора данных с помощью получения кросс-доменного запроса из iframe.

Использование

При использовании iframe, по завершению сценария сбора данных заявителя на фронте придет PostMessage:

{
  app: 'rim',
  method: 'flowFinished',
  context: 'biometrics'
}

Параметры PostMessage

Атрибут	Описание
app	Источник сообщения. Всегда принимает значение “rim”
method	Результат работы iframe. На данном этапе принимает значение `flowFinished`, сообщающее о прохождении этапа сбора данных
context	Подробности о результате работы. Может принимать одно из значений в зависимости от выбранного способа идентификации: – `biometrics` — получение данных через распознавание – `mobileid` — получение данных через Mobile ID – `manual` — ручной ввод данных

Пример обработки

window.addEventListener('message', function(event) {
  // Проверяем источник сообщения
  if (event.origin !== 'https://rim.idscan.mts.ru') {
    return;
  }

  const { app, method, context } = event.data;

  if (app === 'rim' && method === 'flowFinished') {
    console.log('Идентификация завершена:', context);

    // Получаем результаты через API
    if (context === 'biometrics' || context === 'mobileid' || context === 'manual') {
      // Запрос данных через API
      fetchIdentificationResults(identificationId);
    }
  }
});

Callback (HTTP)

Колбэк предназначен для оповещения о переходе запроса в конечный статус.

Настройка

Для работы с колбэком требуется:

Передать менеджеру МТС KYC IP-адрес и порт, на который будет совершаться колбэк
Подготовить со своей стороны сервис, принимающий колбэк
Убедиться, что endpoint доступен для сетевого контура МТС

Формат колбэка

Колбэк отправляется в формате JSON:

{
  "externalId": "string",
  "id": "string",
  "identificationStatus": "identificationSucceeded"
}

Параметры колбэка

Атрибут	Тип	Описание	Размер	Обязательный
externalId	string	Идентификатор заявителя	0..255	Нет
id*	string	Идентификатор запроса	1..255	Да
identificationStatus*	string	Статус запроса	0..255	Да

Статусы в колбэке

Колбэк отправляется при переходе заявки в один из конечных статусов:

identificationSucceeded — заявка прошла идентификацию
identificationFailed — заявка не прошла идентификацию
systemError — произошла системная ошибка
identificationManuallyAccepted — заявка одобрена вручную
identificationManuallyRejected — заявка отклонена вручную

Пример обработки колбэка

// Пример обработки колбэка на Node.js
app.post('/kyc-callback', (req, res) => {
  const { externalId, id, identificationStatus } = req.body;

  // Логируем получение колбэка
  console.log('Received callback:', { externalId, id, identificationStatus });

  // Проверяем статус
  if (identificationStatus === 'identificationSucceeded') {
    // Заявка успешно прошла идентификацию
    // Получаем полные данные через API
    fetchIdentificationData(externalId, id);
  } else if (identificationStatus === 'identificationFailed') {
    // Заявка не прошла идентификацию
    handleFailedIdentification(externalId, id);
  }

  // Отвечаем 200 OK
  res.status(200).send('OK');
});

Если колбэк не пришёл

В случае, если колбэк не приходит длительное время (более 400 минут):

Заберите данные по идентификатору запроса методом: GET /api/v2/applicants/{externalId}/identifications/{requestGuid}
Не дожидайтесь колбэка — он может не прийти в случае обрыва сетевой связности и прочих технических неполадок

Сравнение PostMessage и Callback

Характеристика	PostMessage	Callback (HTTP)
Применение	Только для iframe интеграции	Для всех типов интеграции
Скорость	Мгновенное уведомление	Зависит от сетевой задержки
Настройка	Не требуется	Требуется настройка endpoint
Надёжность	Зависит от браузера	Более надёжно