Порядок переходу на JWS Authorization 2.0
Для безшовного переходу з поточного формату авторизації на JWS Authorization 2.0 рекомендуємо виконувати інтеграцію поетапно.
1
2
3
Останнє оновлення
Для безшовного переходу з поточного формату авторизації на JWS Authorization 2.0 рекомендуємо виконувати інтеграцію поетапно.
У новому форматі авторизації запити до Ecom передаються у вигляді JWS:
HEADER.PAYLOAD.SIGNATUREде:
HEADER — містить службову інформацію, необхідну для перевірки запиту;
PAYLOAD — містить параметри API-запиту;
SIGNATURE — цифровий підпис запиту, сформований приватним ключем мерчанта.
Перед початком інтеграції рекомендуємо ознайомитися з принципом формування та підписання JWS: Робота з підписанням
Для роботи з JWS необхідно згенерувати пару криптографічних ключів:
Private Key — використовується мерчантом для підписання JWS-запитів;
Public Key — використовується Банком для перевірки підпису запитів мерчанта.
Private Key повинен зберігатися виключно на стороні мерчанта та не передаватися Банку або третім особам.
Генерацію ключів необхідно виконувати відповідно до параметрів та алгоритмів, зазначених у документації : Генерація ключів
Для підключення JWS Authorization 2.0 до існуючого merchantId необхідно передати Банку згенерований Public Key.
Публічний ключ необхідно направити на:
aromashkan@alliancedigital.tech
Після реєстрації ключа на стороні Банку мерчанту буде надано ідентифікатор ключа — kid.
Отриманий kid необхідно використовувати при формуванні HEADER JWS-запитів.
Наприклад:
{
"alg": "ES256",
"kid": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
"ts": "1769174930000",
"targetUrl": "/ecom/jws/payments/create/purchase_v3"
}Для кожного API-запиту необхідно:
Сформувати HEADER.
Сформувати PAYLOAD відповідно до документації конкретного ендпоінта.
Закодувати необхідні частини JWS.
Сформувати SIGNATURE за допомогою Private Key мерчанта.
Передати сформований JWS на відповідний JWS-ендпоінт Ecom.
При формуванні HEADER необхідно враховувати:
alg — алгоритм підписання;
kid — ідентифікатор зареєстрованого публічного ключа мерчанта;
ts — час формування JWS;
targetUrl — URL API-методу, для якого формується JWS.
Детальніше: https://docs.merchant.alb.ua/avtorizaciya-2.0/robota-z-pidpisannyam
Якщо мерчант використовує API-методи, в яких передаються карткові дані, необхідно додатково реалізувати їх шифрування.
Шифрування карткових даних та підписання JWS є окремими механізмами.
Детальніше:
https://docs.merchant.alb.ua/avtorizaciya-2.0/shifruvannya-kartkovikh-danikh
Відповіді Ecom повертаються мерчанту у форматі JWS та містять цифровий підпис Банку.
Перевірка відповіді, не є обов'язковим
На стороні мерчанта необхідно реалізувати перевірку цього підпису.
Загальний алгоритм:
Отримати JWS-відповідь.
Декодувати HEADER.
Отримати значення kid.
За kid визначити публічний ключ Банку.
Перевірити SIGNATURE.
Після успішної перевірки обробити дані з PAYLOAD.
Якщо необхідний публічний ключ Банку ще не був отриманий, його можна отримати через:
/ecom/keys/public_key/get_v1Детальніше про перевірку підпису:
Перед переходом на JWS Authorization 2.0 у production необхідно провести тестування інтеграції.
Для цьго рекомендуємо ознайомитись з покроковим описом робот з JWS на прикладі операції Purchase
Після успішного проходження тестування можна погоджувати переключення інтеграції на JWS Authorization 2.0.
Останнє оновлення