Регуляторне API Openbanking

Регулятором API виступає НБУ (ЄМА)

Терміни

PSU (Payment Service User) - користувач платіжних послуг

Домен для API викликів

vOpenBanking.radabank.com.ua

Безпека API викликів

Transport Layer Security (TLS)

Зв'язок між TPP та нами завжди захищений за допомогою TLS версії 1.2 або вище. TLS (Transport Layer Security) — це криптографічний протокол, який використовується для захисту комунікацій у мережі. Він забезпечує безпечне та зашифроване з'єднання між вами та нашими API.

Сертифікати

Клієнтський сертифікат

Цей сертифікат використовується для встановлення TLS-сесії між застосунком TPP та платформою. Це дає змогу забезпечити те, що повідомлення, надіслані між двома сторонами, не будуть прочитані або викрадені. Сертифікат розташовується на транспортному рівні та перевіряється веб-браузером. Сертифікат клієнта є обов'язковим для живих застосунків.

Сертифікат від регулятора

Європейське законодавство (стаття 34 з EBA Regulatory Technical Standard щодо Strong Customer Authentication, далі 'RTS') та Національний банк України передбачають використання QWAC та QSealC TPP для доступу до регуляторних API-сервісів.

Регуляторні сертифікати містять унікальний ідентифікатор ліцензії TPP, за допомогою якого Платформа відкритого банкінгу та банки можуть ідентифікувати TPP та перевірити його юридичний статус у Національному реєстрі TPP. Ці сертифікати також містять ролі PSD2 (PISP, AISP, PIISP), на основі яких Платформа може обмежити використання регуляторних API клієнтськими застосунками. Наприклад, якщо TPP не має призначеної ролі "PISP", то цей TPP не зможе використовувати API сервісу ініціювання платежів (PIS).

Таким чином, для використання регуляторних API ви повинні отримати сертифікати QWAC та QSealC від вашого національного QTSP (Quality Trust Service Provider), завантажити їх через сторінку управління сертифікатами на порталі розробника та прив'язати їх до одного або кількох живих застосунків.
Регуляторні сертифікати мають бути завантажені з наступними розширеннями: .crt, .cer, .pem

QWAC

Qualified Web Authentication Certificate використовується для встановлення безпечного TLS-з'єднання між TPP та Платформою. Він розташовується на транспортному рівні та перевіряється веб-браузером.

QsealC

Цей Qualified Electronic Seal Certificate використовується для підпису API-запитів до XS2A. Це допомагає забезпечити незмінність повідомлень, що обмінюються з Платформою.

Щоб правильно підписати запит, TPP має розрахувати хеш тіла HTTP запиту і помістити його в заголовок "digest". Потім потрібно сформувати рядок, закодований в base64, сформований із заголовків "digest", "x-request-id", "psu-id" і "tpp-redirect-uri", підписати цей рядок приватним ключем, пов'язаним з їхнім QSealC, і помістити його в заголовок "signature" разом з відповідними метаданими. Платформа перевіряє підпис за допомогою сертифіката QSealC, прикріпленого в заголовку "tpp-signature-certificate".
https://www.youtube.com/watch?v=BiiVKoo-fTc

Ліміти на API виклики

Всі API, що розміщені на платформі, лімітовані за кількістю викликів для захсту від DDoS атак та задля гарантій стабільності продуктивності.

Облікові дані клієнта

Банк надає провайдеру ідентіфікатор клієнта, секретний ключ ідентифікатор ключа. Провайдер генерує hash код за допомогою метода HMAC. В якості даних бере скомбіновану строку з ідентифікатора клієнта, ідентифікатора ключа і поточної дати у форматі «yyyy.mm.dd».

OAuth 2.0

API захищені за допомогою OAuth 2.0 Client Credentials Grant, що забезпечує надійний механізм автентифікації. Щоб отримати доступ до API, треба отримати токен доступу з виділеної кінцевої точки:

POST /gate_openbank/providers/{{providerId}}/v0/openbank/token

Запит повинен включати заголовки

--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'X-Request-ID' \
- header ‘Signature' \
- header ‘Signdate’ \

Правила та конвенції API

Ми прагнемо ділитись досвідом, що перевершує очікування. Ми побудували наш відкритий API на основі архітектури Representational State Transfer Service (REST), стандартного HTTP та легкого для читання і запису JavaScript Object Notation (JSON). Ми дотримуємося ідеології API специфікацій та інструкцій з впровадження від Berlin Group, а також розширяємо відповідні документації для відповідності вимогам національного регулятора.

Методи HTTP API

Усі сервіси доступні через API, використовуючи методи HTTPS на основі REST:

GET: Читає ресурс і повертає його;
POST: Створює новий ресурс;
PUT: Запитує збереження наданої сутності за наданим URI;
DELETE: Видаляє ресурс, ідентифікований URI.

Нові основні версії регуляторних API залежатимуть від випусків мандатів Національного банку України.

Коди відповідей HTTP та коди помилок

Разом із HTTP статус кодами Платформа також повертає коди помилок для підвищення прозорості та полегшення обробки винятків TPP.

Помилки завжди повертаються у наступному форматі:

Copy

"apiClientMessages": [

   {

     "category": "ERROR", //can be either ERROR or WARNING

     "code": "FORMAT_ERROR", //error code

     "text": "Invalid request for some reason" //explanation or error code

   }

Нижче наведено список неспецифічних кодів помилок, які повертаються як для Преміум, так і для Регуляторних API:
У цій документації ви також можете знайти специфічні коди помилок для сервісів PIS (Payment Initiation Service) та AIS (Account Information Service).
Scenario
Status code - Error code
Non-existent URL (including missing or unexpected path parameter)

404 - RESOURCE_UNKNOWN

Unexpected or non-existent HTTP method

405 - SERVICE_INVALID

Unexpected Content-Type header

415 – SERVICE_INVALID

Unexpected Accept header

406 - REQUESTED_FORMATS
_INVALID

Value of query parameter does not match data type in OAS

400 - PARAMETER_NOT_CONSISTENT

Query parameter is missing

400 - PARAMETER_NOT_CONSISTENT

Unexpected query parameter

400-PARAMETER_NOT_SUPPORTED

Value of header (except Accept and Content-Type) OR field in body does not match data type in OAS or missing

400 - FORMAT_ERROR

Header (except Accept and Content-Type) OR field in body is missing

400 – FORMAT_ERROR

Unexpected header OR field in body

400 – FORMAT_ERROR

Body is missing or JSON has invalid format

400 – FORMAT_ERROR

Application sends request with certificate associated with another app

401 - CERTIFICATE_INVALID

Certificate has been revoked

401 - CERTIFICATE_REVOKED

Certificate has expired

401 - CERTIFICATE_EXPIRED

No signature

401 - SIGNATURE_MISSING

Invalid signature

401 - SIGNATURE_INVALID

Expired token

401 - TOKEN_EXPIRED

System cannot identify TPP by token

401 - TOKEN_UNKNOWN

Sandbox token is used for live API

401 - TOKEN_INVALID

Missing token

401 - TOKEN_MISSING

Operation (with specific version) is out of application’s scopes

403 - OPERATION_NOT_ALLOWED

Operation (with specific version) is not offered by the provider or provider is no longer active

403 - OPERATION_NOT_ALLOWED

TPP hits the limit set for the product by bank

429 - OPERATION_NOT_ALLOWED