Підключення та mTLS-сертифікати
Для підключення до WSGATE використовується захищене HTTPS-з’єднання з взаємною TLS-аутентифікацією - mTLS.
Під час встановлення з’єднання клієнт перевіряє сертифікат сервера UKRCARD, а UKRCARD перевіряє клієнтський сертифікат.
Для роботи необхідно налаштувати:
▪️ клієнтський сертифікат;
▪️ відповідний приватний ключ;
▪️ сертифікат центру сертифікації або ланцюжок довіри;
▪️ мережевий доступ до відповідного середовища.
1. Способи підключення
Для WSGATE доступні два способи підключення:
- через погоджений VPN-канал до внутрішніх ресурсів UKRCARD;
- через публічну адресу, доступну з мережі Інтернет.
Обидва способи використовують mTLS.
Сертифікати для VPN-підключення та для підключення через публічну адресу не є взаємозамінними.
2. Підключення через VPN
Підключення через VPN виконується до внутрішніх URL WSGATE через VPN-канал.
URL сервісів не змінюються. Для переходу необхідно оновити VPN-налаштування та забезпечити маршрутизацію до нових внутрішніх IP-адрес:
▪️ тестове середовище - 10.0.24.224;
▪️ продуктивне середовище - 10.0.11.230.
Для mTLS-підключення через VPN використовуються сертифікати, випущені внутрішнім центром сертифікації UKRCARD.
UKRCARD окремо надає:
▪️ оновлений CA - сертифікат внутрішнього центру сертифікації;
▪️ за потреби - додаткові параметри для налаштування довіреного ланцюжка сертифікатів.
Перехід на оновлений CA-сертифікат необхідно завершити до 01.08.2026.
Після завершення перехідного періоду використання попереднього CA-сертифіката буде припинено.
3. Підключення через VPN
Підключення через VPN виконується через погоджений VPN-канал до внутрішніх URL WSGATE.
Для доступу використовуються такі адреси:
| Середовище | URL | IP-адреса для налаштування VPN |
|---|---|---|
| Тестове | https://pre-wsgate.ukrcard.com.ua | 10.0.24.224 |
| Продуктивне | https://wsgate.ukrcard.com.ua | 10.0.11.230 |
Для mTLS-підключення через VPN використовуються сертифікати, випущені внутрішнім центром сертифікації UKRCARD.
UKRCARD надає:
▪️ клієнтський сертифікат для VPN-підключення;
▪️ CA-сертифікат внутрішнього центру сертифікації;
▪️ за потреби - додаткові параметри для налаштування довіреного ланцюжка сертифікатів.
Важливо для чинних клієнтів: сертифікати, які раніше використовувалися для VPN-підключення до WSGATE, будуть відкликані 01.08.2026. До цієї дати необхідно отримати та встановити новий сертифікат для VPN-підключення.
Нові клієнти отримують актуальний сертифікат для VPN-підключення у межах стандартного процесу підключення.
4. Підключення через публічну адресу
Для WSGATE також доступне підключення через публічні DNS-імена з мережі Інтернет.
| Середовище | URL |
|---|---|
| Тестове | https://prewsgate.ukrcard.com.ua |
| Продуктивне | https://ewsgate.ukrcard.ua |
Підключення через публічну адресу також використовує mTLS.
Для цього способу підключення необхідно отримати окремий клієнтський сертифікат. Сертифікат для VPN-підключення не може використовуватися для підключення через публічну адресу.
Нові клієнти можуть замовити сертифікат для публічного підключення під час узгодження параметрів інтеграції.
Чинним клієнтам для отримання сертифіката для публічного підключення необхідно повторно сформувати CSR. Під час створення CSR необхідно зазначити CN, який використовувався раніше.
Після успішного тестування клієнт може:
▪️ використовувати тільки VPN-підключення;
▪️ використовувати тільки підключення через публічну адресу;
▪️ використовувати обидва способи підключення - один як основний, інший як резервний.
5. Процес підключення
отримайте облікові дані
Вам призначається ідентифікатор зовнішньої системи ExtSystemid, які ви використовуватимете при генерації сертифіката. Також вам призначається логін login і пароль password, які ви використовуватимете надалі при кожному виклику API методів.
згенеруйте TLS-сертифікат для вашого сервісу
Відповідальна особа з вашого боку повинна створити запит на підпис сертифіката (CSR):
Приклад команди для генерації CSR (OpenSSL):
openssl req -nodes -newkey rsa:2048 -keyout private.key -out request.csr -subj "/emailAddress=admin@ukrcard.ua/C=UA/O=NATIVE APPS/OU=IT/CN=F102_PURCHASE4_Tarascha_001" -sha256
| Параметр | Опис |
| req | Використовується для створення запиту на підпис сертифіката (CSR) |
| -nodes | Генерує приватний ключ без шифрування (без запиту пароля на нього) |
| -newkey rsa:2048 | Генерує новий ключ RSA довжиною 2048 біт |
| -keyout private.key | Файл, у який буде збережено приватний ключ |
| -out request.csr | Файл вихідного CSR-запиту |
| -subj | Визначає інформацію про сертифікат у форматі Distinguished Name (DN) |
| emailAddress | Email відповідального підрозділу або сервісу. На цей email буде відправлен підписаний сертифікат. А також на цей email прийде запит на подовження строка дії в майбутньому (наприклад: admin@ukrcard.ua) |
| C(Country) | Код країни (наприклад: UA) |
| O(Organization) | Назва компанії (наприклад: UKRCARD) |
| OU(Org Unit) | Відділ (наприклад: IT) |
| CN(Common Name) | Унікальний ідентифікатор сертифіката, що включає:
🔹 ExtSystemid (наприклад: F102_PURCHASE4) 🔹 Місто (наприклад: Tarascha) 🔹 Додатковий ідентифікатор (наприклад: 001) |
| -sha256 | Використовує алгоритм хешування SHA-256 |
- request.csr (Запит на підпис. Файл який треба відправити на підпис security@ukrcard.ua)
- private.key (Закритий ключ, який треба зберігати в безпечному місці!)
Відправка CSR на підпис
Надішліть згенерований request.csr на email security@ukrcard.ua.
💡
Формат листа:
Тема: Запит на підпис TLS-сертифіката для <назва компанії>
Вкладення: request.csr
Коментар (якщо потрібно): Додаткові побажання або деталі
Отримання сертифіката
Після обробки запиту ви отримаєте архів із підписаним сертифікатом у відповідь на ваш email.
💡
Вміст архіву:
certificate.pem - підписаний сертифікат
ca-bundle.pem - ланцюжок довіри (може знадобитися)
Застосування сертифіката
-
Розпакуйте архів і отримайте certificate.pem.
-
Встановіть сертифікат у ваш сервіс відповідно до документації вашого програмного забезпечення.
-
Переконайтеся, що:
- Закритий ключ (private.key) знаходиться у вас на сервері.
- Сертифікат (certificate.pem) використовується під час з'єднання з Ukrcard.
- При необхідності, додайте ca-bundle.pem для верифікації довіри.
===============================================
6. Створення CSR
На стороні клієнта мають бути налаштовані:
▪️ клієнтський сертифікат;
▪️ відповідний приватний ключ;
▪️ сертифікат або ланцюжок сертифікатів центру сертифікації, якщо це необхідно для перевірки довіри.
Сертифікати для підключення через VPN та через публічну адресу не є взаємозамінними.
2 Підключення через зовнішній URL
API-запити виконуються через зовнішній HTTPS endpoint, доступний через захищену інфраструктуру WAF. У цьому випадку налаштування VPN не є обов’язковим, що спрощує та прискорює старт інтеграції.
В обох варіантах взаємодія з API виконується тільки по HTTPS. Для доступу до сервісів використовуються облікові дані клієнта та TLS-сертифікат, отриманий у процесі підключення.
Конкретний канал підключення, URL-адреси API та параметри доступу погоджуються з технічною командою Ukrcard окремо для тестового та продуктивного середовища.
2.3. Отримайте доступ до тестової платформи
1️⃣ отримайте облікові дані
Вам призначається ідентифікатор зовнішньої системи ExtSystemid, які ви використовуватимете при генерації сертифіката. Також вам призначається логін login і пароль password, які ви використовуватимете надалі при кожному виклику API методів.
2️⃣ безпечного з'єднання
Наші API методи працюють тільки по протоколу HTTPS, тому для забезпечення безпечного з'єднання необхідно згенерувати TLS-сертифікат.
3️⃣ згенеруйте TLS-сертифікат для вашого сервісу
💠 Генерація CSR (Certificate Signing Request)
Відповідальна особа з вашого боку повинна створити запит на підпис сертифіката (CSR):
Приклад команди для генерації CSR (OpenSSL):
openssl req -nodes -newkey rsa:2048 -keyout private.key -out request.csr -subj "/emailAddress=admin@ukrcard.ua/C=UA/O=NATIVE APPS/OU=IT/CN=F102_PURCHASE4_Tarascha_001" -sha256
| Параметр | Опис |
| req | Використовується для створення запиту на підпис сертифіката (CSR) |
| -nodes | Генерує приватний ключ без шифрування (без запиту пароля на нього) |
| -newkey rsa:2048 | Генерує новий ключ RSA довжиною 2048 біт |
| -keyout private.key | Файл, у який буде збережено приватний ключ |
| -out request.csr | Файл вихідного CSR-запиту |
| -subj | Визначає інформацію про сертифікат у форматі Distinguished Name (DN) |
| emailAddress | Email відповідального підрозділу або сервісу. На цей email буде відправлен підписаний сертифікат. А також на цей email прийде запит на подовження строка дії в майбутньому (наприклад: admin@ukrcard.ua) |
| C(Country) | Код країни (наприклад: UA) |
| O(Organization) | Назва компанії (наприклад: UKRCARD) |
| OU(Org Unit) | Відділ (наприклад: IT) |
| CN(Common Name) | Унікальний ідентифікатор сертифіката, що включає:
🔹 ExtSystemid (наприклад: F102_PURCHASE4) 🔹 Місто (наприклад: Tarascha) 🔹 Додатковий ідентифікатор (наприклад: 001) |
| -sha256 | Використовує алгоритм хешування SHA-256 |
- request.csr (Запит на підпис. Файл який треба відправити на підпис security@ukrcard.ua)
- private.key (Закритий ключ, який треба зберігати в безпечному місці!)
4️⃣ Відправка CSR на підпис
Надішліть згенерований request.csr на email security@ukrcard.ua.
💡
Формат листа:
Тема: Запит на підпис TLS-сертифіката для <назва компанії>
Вкладення: request.csr
Коментар (якщо потрібно): Додаткові побажання або деталі
5️⃣ Отримання сертифіката
Після обробки запиту ви отримаєте архів із підписаним сертифікатом у відповідь на ваш email.
💡
Вміст архіву:
certificate.pem — підписаний сертифікат
ca-bundle.pem — ланцюжок довіри (може знадобитися)
6️⃣ Застосування сертифіката
-
Розпакуйте архів і отримайте certificate.pem.
-
Встановіть сертифікат у ваш сервіс відповідно до документації вашого програмного забезпечення.
-
Переконайтеся, що:
- Закритий ключ (private.key) знаходиться у вас на сервері.
- Сертифікат (certificate.pem) використовується під час з'єднання з Ukrcard.
- При необхідності, додайте ca-bundle.pem для верифікації довіри.
📩 Якщо виникли питання – звертайтеся: security@ukrcard.ua
2.4. Розробіть свою реалізацію
На основі отриманої документації та сертифікатів розробіть власне рішення для інтеграції з Ukrcard.
2.5. Виконайте тестування в тестовому середовищі
Перед виходом у продакшн необхідно виконати повне тестування інтеграції в тестовому середовищі Ukrcard.
-
Використовуйте тестові сертифікати та API-ендпоінти для тестування.
-
Переконайтеся, що всі запити коректно підписані.
-
Виконайте базові операції: авторизація платежу, проведення платежу, скасування.
-
Перевірте поведінку системи у разі помилок та таймаутів.
-
Підтвердіть, що ваша система відповідає вимогам безпеки (TLS, PCI DSS).
-
Узгодьте з технічною командою Ukrcard фінальні налаштування перед виходом у продакшн.
-
Після успішного тестування узгодьте з Ukrcard дату переходу в продуктивне середовище.
Цей процес дозволяє переконатися, що інтеграція працює коректно, перш ніж запускати її у реальну експлуатацію.
2.6. Отримайте доступ до продуктивного середовища
- Отримайте реальний ідентифікатор зовнішньої системи
ExtSystemidта продуктивніloginі парольpassword; - Сформуйте та надішліть TLS-сертифікат на підпис, та отримайте готовий для використання в архіві;
- Звернітся до обраного банка-еквайра (список) для отримання умов обслуговування та інформації про тарифи;
- Узгодьте та підпишіть угоду з банком-еквайром про надання обраних сервісів (послуг);
- Банк-еквайєр надсилає заповнену заявку для реєстрації терміналу з переліком дозволених операцій;
2.7. Виконайте фінальні налаштування і тести перед переходом у прод
- Налаштуйте реальне оточення;
- Проведіть пілотну операцію;
- Ми підтверджуємо коректність виконання операції
- Можете запускати потік клієнтів
2.8. Запустіть інтеграцію у продуктивному середовищі