Рекомендации по реализации интеграции для Пользователя API

Необходимо, чтобы Пользователь API:

1. Прошел процедуру регистрации на Портале АО «НПК» (см. подробнее в Регистрация и авторизация в Портале НПК)

2. Подал заявку на подключение к Open Banking в качестве Пользователя API (см. подробнее в Подключение к Open Banking/Open API)

3. Зарегистрировал приложение Участника (см. подробнее в Пользователям API (добавление и использование приложения))

Общее описание процесса:

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

• Реализовать перенаправление Клиента для прохождения аутентификации и регистрации его согласия на доступ к данным, реализовать получение кода авторизации.

• Реализовать получение токена доступа.

• Реализовать получение данных посредством интерфейсов API. Для получения информации посредством интерфейсов API используется полученный токен доступа.

• Реализовать отображение клиенту полученной информации в приложении Пользователя API.

Общая схема процесса получения сведений о банковском счете клиента

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

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

Если клиент еще не дал согласие на доступ к его счетам для приложения Пользователя API, необходимо изменить список банков, на доступ к счетам в которых предоставляется согласие, или истек токен доступа, то выполняется переход к шагу 2.

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

Общая диаграмма взаимодействия

Если в ОС Android при проведении liveness-сессии не отображается изображение клиента (см. пример на рисунке ниже), то потенциальным решением проблемы может являться применение следующих параметров:

webView.settings.allowContentAccess = true; webView.settings.mediaPlaybackRequiresUserGesture = false; webView.settings.domStorageEnabled = true

WebKit в Android, позволяет видео компонентам запускаться только по действию пользователя, при этом для корректной работы сервисов ЦОИД камера запускается программными средствами (autoplay), WebKit блокирует данное действие и выдает ошибку. Чтобы избежать этого, необходимо в компоненте webView указать данную настройку.

Пример отсутствия доступа к контенту для WebView

В IOS необходимо использовать SafariWebView. WKWebView не поддерживается.

Перенаправления клиента для прохождения аутентификации

Для перенаправления клиента для прохождения аутентификации необходимо:

1) Реализовать получение URL-адреса для перенаправления клиента. Описание метода «Получить URL-адрес для перенаправления клиента» (POST /v1/auth/generate-user-url) приведено в https://auth-openapi.npck.kz/#tag/Auth/operation/generateUserUrl.

Примечание: Метод получения URL-адрес для перенаправления клиента POST /oauth2/generate-user-url (см. https://auth-openapi.npck.kz/#tag/Auth/operation/generateUserUrlDeprecated) является устаревшим, рекомендуется перейти на использование метода POST /v1/auth/generate-user-url (см. https://auth-openapi.npck.kz/#tag/Auth/operation/generateUserUrl).

2) Реализовать перенаправление пользователя на полученный URL-адрес.

То к каким данным клиента запрашивается доступ определяется значениями, указанными в параметре scopes (могут быть указаны несколько значений) при запросе URL-адреса для перенаправления клиента:

• accounts - доступ к списку счетов клиента

• account_balance - доступ к информации о балансе счета

• account_transactions - доступ к списку транзакций счета

Время действия URL-адреса для перенаправления (время «жизни») составляет 15 минут

1. Клиенту отображается форма аутентификации. Клиент проходит двухфакторную аутентификацию личности.

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

Клиент может отклонить согласие на доступ к его данным.

Если клиент отклоняет согласие на доступ к его данным или происходит ошибка, то клиент будет перенаправлен на указанный на шаге 2 redirectUri, с указанием кода ошибки, по следующему шаблону:

[redirectUri]?errorCode=[error code]&state=[state]

В таком случае процесс завершается, код авторизации не предоставляется.

1. После того, как клиент выполнит все действия по предоставлению согласия на доступ к его данным, осуществляется его возврат в приложение Пользователя API.

Если аутентификация клиента проходит успешно и он дает согласие на доступ к его данным, то клиент перенаправляется обратно в приложение Пользователя API (на указанный в запросе redirectUri) с одноразовым кодом авторизации (code), по следующему шаблону:

[redirectUri]?code=[authorization code]&state=[state]

Код авторизации является одноразовым.

Время действия кода авторизации (время «жизни») составляет 300 секунд

Редирект из webview в случае SafariWebView нужно перехватывать через диплинк (deeplink)

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

Получение токена доступа

Для получения токена доступа необходимо:

1) Реализовать формирование запроса получения токена доступа, используя полученный код авторизации. Описание используемого для этого метода приведено в https://auth-openapi.npck.kz/#tag/Auth/operation/getOauthToken.

2) Реализовать отправку сформированного запроса и получение токена доступа.

Токен доступа имеет формате JWT (см. RFC 7519). Токен доступа может использоваться для получения сведений о счете клиента посредством API, в течении срока его действия, после истечения срока действия необходимо получить новый токен доступа.

Примечание: Дополнительно доступен метод получения списка публичных ключей для проверки токена (см. https://auth-openapi.npck.kz/#tag/Auth/operation/wellKnown).

Дополнительно доступен опциональный метод интроспекции токена (см описание https://auth-openapi.npck.kz/#tag/Auth/operation/oauth2Introspect). Данный метод используется для проверки того, активен или истек ли конкретный токен, а также для получения связанных с токеном метаданных.

Важно! Токен доступа должен сохраняться в тайне и не передаваться в публичный доступ, должен храниться на серверной стороне приложения, и вся обработка, связанная с ним, должна производиться на серверной стороне приложения.

1. Приложение Пользователя API получает информацию о счетах клиента посредством интерфейсов API используется токен доступа, полученный на предыдущем шаге. Перечень методов API для получения информации о банковском счете клиента, описание форматов запросов и ответов приведены в https://accounts-openapi.npck.kz/.

API v1 является устаревшим, рекомендуется перейти на использование API v2

1. Приложение Пользователя API отображает клиенту полученную информацию о его счетах (см. рекомендации Рекомендации для мобильного приложения).