Account Information Service (AIS)
Послуга з надання відомостей з рахунків дозволяє стороннім надавачам платіжних послуг (Third party provider, TPP) отримувати доступ до інформації про рахунок користувача платіжних послуг (Payment Service User, PSU).
1. Загальна інформація та умови підключення до сервісу
- Архітектура та стандарт
Спеціалізовані інтерфейси побудовані за принципами REST API та базуються на специфікації XS2A (Access to Account), яка реалізована через платформу відкритого банкінгу (Open Banking Platform, OBP). XS2A є стандартним інтерфейсом доступу третіх сторін до платіжних рахунків відповідно до вимог PSD2.
1.2. Транспортний протокол
Протокол: HTTPS (HTTP over TLS/SSL). Усі запити передаються виключно по захищеному каналу HTTPS. Використання незахищеного протоколу HTTP не допускається.
1.3. Формат даних
Формат тіла запитів та відповідей: JSON (JavaScript Object Notation). Заголовок Content-Type: application/json обов'язковий для всіх запитів, що містять тіло (POST).
1.4. Версійність
Поточна версія v2. Версія зазначається у базовому шляху URL: /pis/v2/ та /ais/v2/.
1.5. Обов'язкові заголовки HTTP
- X-Request-Id — унікальний ідентифікатор запиту (UUID формат), наприклад: dc7b16a5-4ac8-4fdc-9c4e-9f9d0387dc07. Використовується для ідентифікації та трасування запиту.
- Content-Type — тип вмісту тіла запиту: application/json (для POST-запитів).
- PSU-ID — ідентифікатор користувача платіжних послуг (PSU) у системі банку.
- PSU-IP-Address — IP-адреса пристрою PSU.
- Consent-ID — ідентифікатор підтвердженої AIS-згоди (для запитів до AIS після авторизації).
- Client-Redirect-URI — URL для перенаправлення PSU після успішної авторизації (SCA Redirect).
- Client-Redirect-Nok-URI — URL для перенаправлення PSU у разі невдалої авторизації (SCA Redirect).
1.6. Процедура взаємодії (AIS Flow)
- TPP створює AIS-згоду (POST /consents/account-access) → отримує consentId.
- TPP запускає авторизацію згоди (POST /consents/account-access/{consent-id}/authorisations) → отримує authorisationId та або psuMessage (Decoupled) або scaRedirect URL (Redirect).
- PSU авторизує згоду (через застосунок банку або банківську веб-сторінку).
- TPP перевіряє статус згоди (GET /consents/account-access/{consent-id}/status) до отримання статусу "valid".
- TPP отримує інформацію про рахунки та транзакції, передаючи Consent-ID у заголовку запиту.
Інтерфейс AIS підтримує два режими сильної автентифікації клієнта SCA (Strong Customer Authentication):
- Decoupled SCA (роз'єднана автентифікація). Процедура: PSU отримує повідомлення або push-сповіщення від Банку та авторизує операцію безпосередньо у застосунку Банку, не залишаючи інтерфейс TPP. TPP отримує у відповіді поле psuMessage з текстом для PSU. Банк самостійно сповіщає PSU про необхідність авторизації.
- Redirect SCA (автентифікація з перенаправленням).Процедура: TPP перенаправляє PSU на URL-адресу банківської SCA-сторінки (scaRedirect.href), де PSU проходить автентифікацію та підтверджує операцію. Після завершення авторизації Банк перенаправляє PSU назад до TPP за адресою Client-Redirect-URI (успіх) або Client-Redirect-Nok-URI (невдача).
1.7. Обмеження та ліміти
- Максимальна частота запитів без присутності PSU: 4 рази на добу (frequencyPerDay ≤ 4).
- Доступна глибина історії транзакцій без додаткового SCA: 90 календарних днів.
1.8. Коди помилок, специфічні для AIS
- 401 — CONSENT_INVALID: згода недійсна або не надає необхідних прав доступу.
- 403 — CONSENT_UNKNOWN: згода не існує.
- 429 — ACCESS_EXCEEDED: перевищено денний ліміт у 4 GET-запити без присутності PSU.
- 400 — FORMAT_ERROR (пагінація транзакцій): параметр dateFrom містить дату, що перевищує 90 днів у минулому, для повторюваної AIS-згоди.
1.9. Реєстрація та сертифікати
Для підключення до спеціалізованих інтерфейсів необхідно:
- пройти реєстрацію на Developer Portal (portal.api.upc.ua);
- отримати та налаштувати цифрові сертифікати для взаємної автентифікації TLS (mTLS) — відповідно до розділу "Certificates" порталу;
- налаштувати електронні підписи запитів — відповідно до розділу "Electronic signatures" порталу;
- зареєструвати застосунок у розділі "Applications" та оформити підписку на відповідний API-сервіс.
Технічні вимоги
- HTTP-клієнт з підтримкою HTTPS/TLS та мутуальної автентифікації (mTLS).
- Підтримка формату JSON для серіалізації та десеріалізації даних.
- Здатність формувати унікальні UUID для заголовка X-Request-Id.
- Реалізація логіки опитування статусу (polling) для перевірки статусу платежу та згоди.
- Реалізація механізму пагінації для обходу великих наборів транзакцій (параметри limit та offset).
- Наявність публічно доступних URL-адрес для Client-Redirect-URI та Client-Redirect-Nok-URI (для Redirect SCA).
Середовища
- Sandbox (тестове середовище): доступне для розробки та тестування інтеграції.
- Production (продуктивне середовище): для реальної взаємодії з платіжними рахунками PSU.
2. Опис функціоналу спеціалізованих інтерфейсів AIS:
2.1. Створення згоди на доступ до рахунку
TPP надсилає запит на створення згоди. У запиті передаються: IBAN рахунку, права доступу, тип згоди, ознака повторюваного доступу, термін дії та максимальна частота запитів на добу. Платформа повертає унікальний ідентифікатор згоди (consentId).
Метод та шлях: POST /ais/v2/consents/account-access
Тіло запиту (JSON):
- access.payments[].account.iban — IBAN рахунку, до якого надається доступ.
- access.payments[].rights — масив прав доступу: "accountDetails", "balances", "transactions". Якщо вказано "balances" або "transactions", право "accountDetails" надається неявно.
- consentType — тип згоди: "detailed".
- recurringIndicator — ознака повторюваного доступу: true (постійний) або false (одноразовий).
- validTo — дата закінчення дії згоди (формат: YYYY-MM-DD).
- frequencyPerDay — максимальна кількість запитів на добу без присутності PSU (максимум: 4).
Відповідь (JSON): consentId (UUID), consentStatus ("received"), _links.startAuthorisation.href.
2.2. Авторизація згоди
Після створення згоди TPP ініціює авторизацію через метод POST. Підтримуються два режими SCA (Decoupled та Redirect). TPP перевіряє статус згоди методом GET /ais/v2/consents/account-access/{consent-id}/status до отримання статусу "valid" або "rejected".
Метод та шлях: POST /ais/v2/consents/account-access/{consent-id}/authorisations
Параметр шляху: consent-id (отримано з попереднього кроку).
Заголовки: Client-Redirect-URI, Client-Redirect-Nok-URI.
Відповідь для Decoupled SCA (JSON): scaStatus, authorisationId, psuMessage.
Відповідь для Redirect SCA (JSON): scaStatus, authorisationId, _links.scaRedirect.href.
TPP перевіряє статус згоди методом GET
Метод та шлях: GET /ais/v2/consents/account-access/{consent-id}/status
Відповідь (JSON): consentStatus — статус згоди ("received", "valid", "rejected" тощо).
2.3. Отримання переліку рахунків
TPP отримує перелік рахунків PSU методом GET, передаючи заголовок Consent-ID з ідентифікатором підтвердженої згоди. Платформа повертає список рахунків із IBAN, валютою, ідентифікатором ресурсу, назвою рахунку та поточними балансами.
Метод та шлях: GET /ais/v2/accounts
Параметр запиту: withBalance=true (для отримання балансів у відповіді).
Заголовок: Consent-ID — ідентифікатор підтвердженої AIS-згоди.
Відповідь (JSON): масив об'єктів accounts з полями: iban, currency, resourceId, name, balances[].balanceAmount, balances[].balanceType, balances[].referenceDate.
2.4. Отримання історії операцій
TPP отримує історію операцій за рахунком методом GET. Банк надає історію операцій за останні 31 день, враховуючи дату запиту. У разі, якщо Банк надає історію операцій за період від 31 до 90 днів, запит може оброблюватись без додаткової SCA-авторизації. Для отримання операцій давніше 90 днів необхідна одноразова AIS-згода (recurringIndicator: false). Підтримується посторінкова вибірка (пагінація) за параметрами limit та offset.
Метод та шлях: GET /ais/v2/accounts/{account-id}/transactions
Параметри запиту:
- dateFrom — дата початку вибірки (без додаткового SCA доступна до 90 днів назад; для давніших транзакцій потрібна одноразова AIS-згода з recurringIndicator: false та правом "transactions").
- limit — максимальна кількість записів транзакцій у відповіді (для пагінації).
- offset — кількість пропущених записів від початку вибірки (для пагінації).
Пагінація: TPP збільшує значення offset на кількість вже отриманих записів. Ознакою завершення є відповідь із кількістю записів, меншою за limit, або порожній список. Якщо параметри пагінації не передані, кількість повернутих транзакцій визначається Банком.
3. Опис програми тестування AIS
Передумови:
- Користувач зареєстрований в системі
- Має дійсний токен доступу (залогінений)
- POST https://{portal_url}/auth/realms/participants/protocol/openid-connect/token
