Початок роботи

Switch to English

1. Зв'яжіться з нами

Щоб розпочати інтеграцію з Ukrcard, напишіть нам або зателефонуйте. Ми допоможемо вам пройти всі необхідні етапи підключення.

Протягом короткого часу наша команда зв’яжеться з вами, щоб обговорити:

Вашу бізнес-модель

Ми дізнаємося про ваш бізнес, які послуги ви надаєте та які платіжні операції вам необхідні для роботи.

Географію платежів

В яких країнах ви плануєте працювати та які валюти вам необхідні для обробки платежів

Тип інтеграції

Якщо ви плануєте збирати дані картки клієнта у своєму середовищі та надсилати їх до нашого API, ви повинні переконатися, що ваші компоненти відповідають вимогам PCI DSS та підтвердити нам це в подальшому.

Якщо це не так, ми рекомендуємо вам використовувати Checkout сторінки вже інтегрованих з нами PSP (список), які є готовими рішеннями для обробки платежів без необхідності обробляти чи зберігати платіжну інформацію, або ж використати наш власний продукт Checkout.

Деталі інтеграції

В яких країнах ви плануєте працювати та які валюти вам необхідні для обробки платежів

Після цього ви отримаєте доступ до тестового середовища, а також покрокові інструкції для швидкої інтеграції.

2. Пряма інтеграція

Для прямої інтеграції Укркарт пропонує декілька середовищ

Укркарт пропонує три середовища для інтеграції та тестування: mock, тестове і продуктивне. Кожне з них виконує свою функцію: mock-середовище дозволяє швидко перевірити базову взаємодію без реальних операцій, sandbox (тестове) - використовується для перевірки інтеграції з нашими системами в умовах, наближених до бойових, а через live (продуктивне) середовище виконуються реальні транзакції.

Mock Для дослідження роботи методів

➡

Sandbox Для тестування та інтеграції

➡

Live Для реального використання

2.1. Ознайомитися з документацією API

На цьому ресурсі ви знайдете детальний опис всіх необхідних вам методів, з прикладами, і можливістю викликати методи через MOCK сервер.

Також ми надаємо готову Postman колекцію, яка спрощує тестування всіх наших методів.

Кнопка завантаження нижче завантажить:

1. Колекцію API, яка містить усі виклики нашіх методів у підпапках ukrcard.dev
2. Файл середовища зі змінними, яки ви можете редагувати під себе

2.2. Канал підключення до API

Для роботи з API Ukrcard клієнт може використовувати один із двох варіантів підключення:

1️ Підключення через VPN

API-запити виконуються на внутрішні URL-адреси сервісів Ukrcard, доступні тільки через погоджений VPN-канал. Цей варіант підходить для клієнтів, яким потрібна ізольована мережева взаємодія між інфраструктурою клієнта та Ukrcard.

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.

5️⃣ Отримання сертифіката
Після обробки запиту ви отримаєте архів із підписаним сертифікатом у відповідь на ваш email.

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. Запустіть інтеграцію у продуктивному середовищі