Робота з підписанням

Структура JWS

Типовий JWS складається з трьох частин, розділених крапками (.):

{Base64Url(header)}.{Base64Url(payload)}.{Base64Url(signature)}

Де:

  • header — описує загальні мета данні

{
    "alg": "ES256",  // Алгоритм підписання 
    "kid": "uuid",  // Ідентифікатор публічного ключа (надається від співробітника банку)
    "ts" : "1769174930000", // Дата та час у форматі timestamp в мілісекундах
    "targetUrl" : "/ecom/jws/payments/create/purchase_v3" // URL на який надсилається запит
}
  • payload — дані, які потрібно передати (необхідні данні для коженого запиту, дивитись у документації Платіжні методи H2Harrow-up-right).

  • signature — цифровий підпис, створений за допомогою приватного ключа відправника.

Приклад JWS:

eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.
eyJ1c2VySWQiOiIxMjMiLCJyb2xlIjoiYWRtaW4ifQ.
MEYCIQDmG...

Як виконується підписання

  1. Формується header (мета дані) payload (дані запиту).

  2. Обидві частини кодуються у формат Base64Url.

  3. Об’єднуються в одне повідомлення:

  4. Це повідомлення підписується приватним ключем (детальніше як отирмати ключ - Генерація ключів) за вказаним алгоритмом .

  5. Результат (signature) додається як третя частина JWS.

Приклад генерації JWS можна переглянути на сайті https://www.jwt.io/arrow-up-right

Приклад коду для генерації підпису:

Вимоги до JWS

1. Загальні вимоги до JWS :

  • Усі запити до API повинні бути підписані за допомогою JWS (JSON Web Signature).

  • Підпис формується відповідно до алгоритму, що відповідає типу ключа, переданого у параметрі kid.

  • При валідації JWS система перевіряє правильність header, payload та signature.

У разі порушення будь-якої з вимог запит відхиляється з помилкою.

2. Вимоги до частини header JWS :

ПІдтримувальні параметри header :

Поле
Опис
Тип
Обов'язкове
Приклад

alg

Алгоритм підпису, що відповідає типу ключа

string

так

kid

Ідентифікатор публічного ключа

string

так

ts

Час генерації JWS по UTC(Kyiv)

number (Unix timestamp, milliseconds)

так

targetUrl

URL, для якого формується запит

string (URL)

так

2.1. Перевірка терміну дії токена (ts)

  • Поле ts повинно містити timestamp (в мілісекундах).

  • JWS вважається дійсним протягом 60 секунд з моменту формування.

triangle-exclamation

Умови помилки:

2.2. Перевірка targetUrl

Система перевіряє, що значення:

  • відповідає формату URL,

  • є дозволеним маршрутом API,

  • відповідає фактичному endpoint, куди надсилається запит. Приклад : Запит надійщо в на- {url}/ecom/jws/payments/create/purchase_v3 Фактичний - /ecom/jws/payments/create/purchase_v3

triangle-exclamation

Умови помилки:

2.3. Перевірка алгоритму підпису (alg)

Значення alg повинно відповідати алгоритму пари ключів, що використовується для підпису ES256.

triangle-exclamation

Умова помилки:

2.4. Перевірка існування ключа (kid)

  • kid повинен відповідати одному з активних ключів мерчанта.

triangle-exclamation

Умова помилки:

3. Вимоги до JWS Payload

Payload JWS повинен містити тіло запиту (request body) у JSON, яке повністю відповідає вимогам конкретного endpoint’у.

Приклад: якщо запит виконується до /ecom/jws/payments/create/purchase_v3, то саме тіло цього запиту (Запит проведення PURCHASE Крок 1arrow-up-right) включається у payload JWS.

3.1. Валідація структури тіла запиту

Payload повинен:

  • містити всі обов'язкові параметри, визначені для відповідного endpoint’у,

  • відповідати JSON схемі,

  • проходити внутрішню бізнес-валідацію.

triangle-exclamation

Умова помилки:

3.2. Перевірка мерчанта (merchantId)

Усі операції повинні виконуватися від імені існуючого мерчанта.

triangle-exclamation

Умова помилки:

Last updated