9. Процеси авторизації, що використовуються у всіх сервісах
Редакція OpenBanking Ukraine
Процеси авторизації використовуються для бізнес-транзакцій у відкритому банкінгу, які потребують автентифікації PSU із застосуванням різних підходів SCA, визначених у розділі 8. Опис у цьому розділі є загальним: відповідні endpoints можуть не дублюватися в специфікаціях сервісів для покращення читабельності, але повні специфікації (включно з endpoints авторизації) доступні у відповідних YAML-файлах.
Підтримуються наступні API-методи для процесів авторизації:
| Endpoints/Resources | Метод | Умова | Опис |
|---|---|---|---|
{resourcepath}/{resourceId}/authorisations}/{authorisation-category} | POST | Mandatory | Запускає процес авторизації з визначеним resourceId. |
9.1. Авторизація ресурсу
Процес авторизації — це процес, який створює новий субресурс авторизації. Відповідний субресурс відображає кроки автентифікації PSU як процес авторизації.
Цей процес ініціюється в наступному сценарії: ASPSP надав гіперпосилання в атрибуті _links у відповіді на запит на ініціювання платіжної операції або створення згоди. Це означає, що API client має явно (explicit) почати процес авторизації шляхом виклику endpoint, вказаного нижче.
Виклик
POST /v2/{resource-path}/{resourceId}/{authorisation-category}
Запускає процес авторизації з визначеним resourceId.
Path Parameters
| Атрибут | Тип | Опис |
|---|---|---|
resource-path | String | Path ресурсу {service}/{product-type}, де: 1) {service} означає тип обслуговування пов’язаної бізнес-операції: consents (для згоди) або payments (для ініціювання платежу). 2) {product-type} означає тип продукту відповідної бізнес-операції: account-access у випадку авторизації згоди; або обраний PSU платіжний продукт: instant-credit-transfers (миттєвий кредитовий переказ), credit-transfers (кредитовий переказ). |
authorisation-category | String | Використовується у випадку авторизації ресурсу платіжної операції або згоди. Можливі значення: authorisations. |
resourceId | String | Ідентифікатор, отриманий у відповіді на виклик створення платіжної операції або створення згоди PSU на надання відомостей з рахунків. |
Query Parameters
Відсутні.
Request Header
| Атрибут | Тип | Умова | Опис |
|---|---|---|---|
X-Request-ID | UUID | Mandatory | ID запиту, унікальний для виклику, як це визначено ініціюючою стороною. |
PSU-ID | String | Conditional | Ідентифікатор PSU-фізичної особи в клієнтському інтерфейсі ASPSP. Повинен передаватися, якщо запит позначений як startAuthorisationWithPsuIdentification і цей атрибут раніше не був переданий. |
PSU-ID-Type | String | Conditional | Тип PSU-ID фізичної особи, необхідний у сценаріях, коли PSU мають кілька типів ідентифікаторів, як можливість доступу. Можливі значення визначені у розділі 8.2. Повинен передаватися, якщо запит позначений як startAuthorisationWithPsuIdentification і цей атрибут раніше не був переданий. |
PSU-Corporate-ID | String | Conditional | Ідентифікатор суб’єкту господарювання (ФОП) в онлайн-каналах ASPSP. Повинен передаватися, якщо запит позначений як startAuthorisationWithPsuIdentification і цей атрибут раніше не був переданий. |
PSU-Corporate-ID-Type | String | Conditional | Тип ідентифікатора суб’єкту господарювання (PSU-Corporate-ID), необхідний у сценаріях, коли PSU мають кілька типів ідентифікаторів, як можливість доступу. Можливі значення визначені у розділі 8.2. Повинен передаватися, якщо запит позначений як startAuthorisationWithPsuIdentification і цей атрибут раніше не був переданий. |
Authorization | String | Conditional | Атрибут заповнюється, якщо обрано OAuth2 як попередній крок для автентифікації PSU. |
Client-SCA-Approach-Preference | String | Optional | Список значень, розділених комами, де перший запис має вищий пріоритет, ніж наступний; або кожен підхід SCA, який взагалі не вказується. Наприклад: "decoupled, redirect" або "decoupled". Цей атрибут може ігноруватися ASPSP. |
Client-Redirect-URI | String | Conditional | URI TPP, куди повинен бути направлений потік транзакцій після перенаправлення. Передбачено для підходу Redirect SCA. Це поле може бути проігноровано ASPSP. Рекомендується завжди використовувати це поле в header. |
Client-Nok-Redirect-URI | String | Optional | Якщо цей URI міститься, TPP просить перенаправити потік транзакцій на цю адресу замість Client-Redirect-URI у разі негативного результату redirect SCA. Це може бути проігноровано ASPSP. |
Request Body
Немає.
Response Code
HTTP response code дорівнює 201.
Response Header
| Атрибут | Тип | Умова | Опис |
|---|---|---|---|
X-Request-ID | UUID | Mandatory | ID запиту, унікальний для виклику, як це визначено ініціюючою стороною. |
ASPSP-SCA-Approach | String | Conditional | Можливі значення: DECOUPLED, REDIRECT. OAuth буде включений у REDIRECT. |
Response Body
| Атрибут | Тип | Умова | Опис |
|---|---|---|---|
transactionFees | Amount | Optional | Може використовуватися ASPSP для передавання загальної комісії за операцію, що стосується основних платежів у випадку платіжного ресурсу. Це поле включає в себе currencyConversionFee, якщо це необхідно. |
currencyConversionFees | Amount | Optional | На даний момент не буде використовуватись в Україні. Може використовуватися ASPSP для транспортування конкретних комісій за конвертацію валюти, пов’язаних з ініційованим кредитним переказом у випадку resourceId платіжного ресурсу. |
estimatedTotalAmount | Amount | Optional | Сума, яка списується з рахунку PSU у випадку використання платіжного ресурсу. Примітка: ця сума включає в себе комісії ASPSP. |
estimatedInterbankSettlementAmount | Amount | Optional | Розрахункова сума, що підлягає перерахуванню отримувачу у разі здійснення платіжної операції. |
scaStatus | SCA Status | Mandatory | Статус SCA. Може приймати значення: started (розпочато SCA); psuIdentified (ідентифікований PSU, пов’язаний з ресурсом авторизації); psuAuthenticated (PSU, пов’язаний з ресурсом авторизації, був ідентифікований та автентифікований); finalised (процедура SCA була успішно завершена; кінцевий статус авторизаційного ресурсу); failed (SCA не пройдений; кінцевий статус авторизаційного ресурсу). |
authorisationId | String | Mandatory | Унікальний ідентифікатор створеного субресурсу авторизації. |
_links | Links | Mandatory | Гіперлінки для подальших кроків. Можливі посилання: 1) scaRedirect (тільки для Redirect SCA): посилання для перенаправлення на автентифікацію PSU. 2) scaOAuth: у разі застосування підходу SCA OAuth2, ASPSP передає URI, за яким можна отримати конфігурацію сервера авторизації. Конфігурація відповідає специфікації метаданих сервера авторизації OAuth 2.0. 3) confirmation: може бути додано ASPSP, якщо у тій самій відповіді повертається або посилання scaRedirect, або scaOAuth. Це посилання визначає URL ресурсу, який потрібно оновити з використанням: (а) коду підтвердження, отриманого після простого процесу автентифікації з перенаправленням через сервер автентифікації ASPSP, або (б) токена доступу, отриманого шляхом подання коду авторизації після інтегрованого процесу автентифікації на основі OAuth з сервером автентифікації ASPSP. Примітка: усі посилання можуть бути відносними або повними, на розсуд ASPSP. |
psuMessage | Max500Text | Optional | Повідомлення для PSU. Надсилати для Decoupled SCA — обов’язково. За замовчуванням текст повідомлення передається українською мовою. |
Приклад
{
"_links": {
"scaStatus": {
"href": "/v2/consents/account-access/c221466e-aa8c-4411-9cc2-690e6f5685ab/authorisations/6c33ee5c-1cef-44ed-9334-3f9c2bfde755"
}
},
"consentId": "c221466e-aa8c-4411-9cc2-690e6f5685ab",
"psuMessage": "Будь ласка, перейдіть в додаток АBank24 для підтвердження надання згоди.",
"scaStatus": "psuIdentified",
"authorisationId": "6c33ee5c-1cef-44ed-9334-3f9c2bfde755"
}