1 Опис функціональності
2 Генерація ключів для мерчанта
- 2.1 Важливі примітки
3 Підписання запитів новим приватним ключем (створення x-sign)
- 3.1 Створення x-sign вручну
  - 3.1.1 1. Поле Private key
  - 3.1.2 2. Поле Input
  - 3.1.3 3. Поле Output
  - 3.1.4 4. Параметр x-sign
4 Створення сесії в зовнішньому еквайрингу | Create session
5 Проведення оплати | Add payment
6 Завершення операції | Complete Hold
7 Повернення заблокованих раніше коштів | Void session
8 Завершення терміну дії платіжної сесії | Expire session
9 Запит на отримання статусу сесії | Get status

Опис функціональності

У адмін-панелі Acquiring3 реалізовано можливість самостійної генерації криптографічних ключів для мерчантів. Приватний ключ завантажується на пристрій користувача у форматі .pem, а публічний ключ автоматично зберігається у Базі даних та у картці відповідного мерчанта.

Функціональність доступна лише користувачам з відповідним дозволом.

Генерація ключів для мерчанта

Натисніть кнопку “Згенерувати ключі” у верхньому меню адмін-панелі.

У модальному вікні з’явиться перелік усіх мерчантів, закріплених за користувачем. Необхідно вибрати одного або декількох мерчантів.

Натисніть “Продовжити”. При цьому система NovaPay здійснить наступне:

автоматично згенерує приватний ключ;
збереже публічний ключ у БД;
запише публічний ключ у картці мерчанта (замінюється при кожній новій генерації приватного ключа);
завантажить приватний ключ на пристрій користувача у форматі .pem.

Відкрийте файл приватного ключа у текстовому редакторі та скопіюйте його для подальшої роботи.

Важливі примітки

Якщо згенерувати ключі для кількох мерчантів одночасно, публічний ключ буде однаковим для них всіх. Це допустимо, один ключ може використовуватися декількома мерчантами.
Якщо мерчанта щойно створено і поле публічного ключа порожнє, то після генерації воно автоматично буде заповнене.
Функціональність підходить як для нових користувачів, так і для існуючих. Якщо клієнт не вміє працювати з ключами, створюється користувач та мерчант без ключів – після отримання доступу клієнт генерує ключі самостійно. До моменту генерації ключа API-запити працювати не будуть.

Підписання запитів новим приватним ключем (створення x-sign)

Після генерації нового приватного ключа необхідно перепідписати всі API-запити, оскільки попередні x-sign стануть невалідними.

Створення x-sign вручну

1. Поле Private key

Після створення ключів мерчант копіює приватний ключ і вставляє його в сервіс https://emn178.github.io/online-tools/rsa/sign/ у поле Private Key.

Параметри, які повинні бути встановлені:

Input Encoding: UTF8
Output Encoding: Base64
Signature Algorithm: SHA-256
Private Key: новий приватний ключ (скопійований з .pem-файлу).

2. Поле Input

Клієнт вставляє тіло запиту на створення сесії в поле Input.

{"merchant_id":"2","client_first_name":"Олег","client_last_name":"Цукор","client_phone":"+380931231234","client_email":"test@gmail.com","callback_url":"https://webhook.site/ea20eca7-129f-41c0-b327-8cc67b47b8de"}

При формуванні тіла запиту дуже важливо зберігати правильні відступи, переноси рядків та інші символи. Навіть зайвий пробіл може змінити підпис запиту та зробити його недійсним.

3. Поле Output

Після вставки тіла запиту у Input, на виході в полі Output клієнт отримує готовий підпис запиту.

4. Параметр `x-sign`

Далі клієнт відправляє запит на створення сесії на URL: https://api-qecom.novapay.ua/v1/session

У Headers запиту в параметрі x-sign передається сформований підпис з поля Output.

Запит надсилається на API з такими параметрами:

curl --location 'https://api-qecom.novapay.ua/v1/session' \
--header 'x-sign: bPfn60HVobyirZZF12FdapUT7zYSVRmpQOHIqyxwXYXAsZ67v1SL2m/MLcxQrujn6ejjdjC7pf7OLIUHKDW/A9TC7tS4gtBV+DrtZ4KFCFh3xTv/wyMb9Ctec0CgOI3N2W1QrOfZAHkxdpweCzCNAF70446pgs7K8JdA0/eTDW9K37BcAgM+U+WH4+xYG0k87AvHQcRt0/9J7V4AcEs4WIxiMj2dtI9+HeLMreNUx0CQcgIKc30h27KWtuMyY+6SCphGRD2WFrLLO+qO+5ZuOlD5dbUSjWl1zGG36LxWbeA2pBc7o2btyiju0DroUHmL4RHwF83v07lG3YOCgYuOWw==' \
--header 'content-type: application/json' \
--data-raw '{"merchant_id":"2","client_first_name":"Олег","client_last_name":"Цукор","client_phone":"+380931231234","client_email":"test@gmail.com","callback_url":"https://webhook.site/ea20eca7-129f-41c0-b327-8cc67b47b8de"}'

Створення сесії в зовнішньому еквайрингу | Create session

Виконайте API-запит створення сесії, підписавши його новим x-sign.
У відповіді буде повернено id сесії.
Використовуйте цей id у всіх подальших запитах (наприклад, payment), кожного разу перепідписуючи body.

Приклад запиту

{
  "merchant_id": "2",
  "client_first_name": "Олег",
  "client_last_name": "Цукор",
  "client_patronymic": "Олегович",
  "client_phone": "+380931231234",
  "client_email": "test@gmail.com",
  "callback_url": "https://callbackurl.com",
  "success_url": "https://successurl.com",
  "fail_url": "https://failurl.com",
  "success_redirect_timeout": 5,
  "metadata": {
  "order_id": "123"
}
}

Приклад успішної відповіді

{
    "id": "ec7c592c-c49b-4e50-a9ff-52b2a12729b5",
    "metadata": {
        "order_id": "123"
    }
}

Проведення оплати | Add payment

Виконайте API-запит створення оплати, підписавши його новим x-sign.
Перейдіть за отриманим посиланням на платіжну сторінку NovaPay.
Проведіть оплату.

Приклад запиту

{
  "merchant_id": "2",
  "session_id": "ec7c592c-c49b-4e50-a9ff-52b2a12729b5",
  "amount": 100,
  "external_id": "BB-1234567",
  "use_hold": true,
  "identifier": "37193071",
  "products": [
    {
      "description": "Футболка",
      "count": 1,
      "price": 100
    }
  ]
}

Приклад успішної відповіді

{
    "url": "https://qecom.novapay.ua/external/pay?sid=ec7c592c-c49b-4e50-a9ff-52b2a12729b5",
    "id": "120191001021",
    "session_id": "ec7c592c-c49b-4e50-a9ff-52b2a12729b5"
}

Завершення операції | Complete Hold

У body запиту замініть session_id на публічний ідентифікатор сесії.
У тій же сесії знайдіть значення ID в платіжній системі: вкладка Платіжні сесії → Сесія зі списку → Публічний ідентифікатор сесії.
Замініть у запиті відповідне поле (operations id) цим значенням.
Перепідпишіть запит новим приватним ключем.

Після виконання запиту Complete Hold оплата вважається повністю завершеною.

Приклад запиту, якщо потрібно списати всю заблоковану суму

{
  "merchant_id": "2",
  "session_id": "ec7c592c-c49b-4e50-a9ff-52b2a12729b5",
  "amount": 100
}

Приклад запиту, якщо потрібно списати частину від заблокованої суми (в цьому випадку захолдовано 100 грн)

{
  "merchant_id": "2",
  "session_id": "ec7c592c-c49b-4e50-a9ff-52b2a12729b5",
  "amount": 50
}

Приклад запиту, коли клієнту при підтвердженні списання потрібно зарахувати кошти іншому отримувачу

{
  "merchant_id": "2",
  "session_id": "ec7c592c-c49b-4e50-a9ff-52b2a12729b5",
  "operations": [
    {
      "id": "120191001036",
      "amount": 50,
      "recipient_identifier": "37193071"
    },
    {
      "id": "120191001037",
      "amount": 100,
      "recipient_identifier": "37193071"
    }
  ]
}

Ідентифікатор операції (id) клієнт отримує у відповіді на запит /v1/payment.

Якщо в межах однієї сесії виконано кілька запитів /v1/payment з умовою холдування (наприклад, користувач додав кілька товарів до одного замовлення), для кожної операції створюється окремий холд і повертається власний id.

Таким чином, у межах однієї session_id може бути декілька операцій із заблокованими коштами.

Під час підтвердження списання (метод /v1/complete-hold) використовується параметр operations.
Він дозволяє керувати тим:

по якій саме операції виконується списання;
яку суму потрібно списати;
якому отримувачу зарахувати кошти.

Приклад успішної відповіді

HTTP/1.1 200 OK
Response body: empty

Повернення заблокованих раніше коштів | Void session

У body запиту замініть session_id на публічний ідентифікатор сесії.
Перепідпишіть запит новим приватним ключем.

Приклад запиту

{
  "merchant_id": "2",
  "session_id": "ec7c592c-c49b-4e50-a9ff-52b2a12729b5"
}

Приклад успішної відповіді

HTTP/1.1 200 OK
Response body: empty

Завершення терміну дії платіжної сесії | Expire session

У body запиту замініть session_id на публічний ідентифікатор сесії.
Перепідпишіть запит новим приватним ключем.

Приклад запиту

{
  "merchant_id": "2",
  "session_id": "ec7c592c-c49b-4e50-a9ff-52b2a12729b5"
}

Приклад успішної відповіді

HTTP/1.1 200 OK
Response body: empty

Запит на отримання статусу сесії | Get status

У body запиту замініть session_id на публічний ідентифікатор сесії.
Перепідпишіть запит новим приватним ключем.

Приклад запиту

{
  "merchant_id": "2",
  "session_id": "ec7c592c-c49b-4e50-a9ff-52b2a12729b5"
}

Приклад успішної відповіді

{
    "id": "ec7c592c-c49b-4e50-a9ff-52b2a12729b5",
    "metadata": {
        "order_id": "123",
        "preprocess_client_id": null
    },
    "status": "holded",
    "created_at": "2026-03-05T08:05:19.547+00:00",
    "client_phone": "+380931231234",
    "client_first_name": "Олег",
    "client_last_name": "Цукор",
    "client_patronymic": "Олегович",
    "pan": "526961xxxx7956",
    "rrn": "9046101",
    "terminal_name": "000000020000001",
    "paytype": "card",
    "approval_code": "911609",
    "card_type": "MasterCard",
    "transaction_status": "APPROVED",
    "amount": "150.00",
    "processing_result": "Successful",
    "operations": [
        {
            "transaction_id": "120191001034",
            "external_id": "BB-1234567",
            "amount": "100.00"
        },
        {
            "transaction_id": "120191001035",
            "external_id": "BB-1234568",
            "amount": "50.00"
        }
    ]
}

Генерація ключів для мерчантів в адмінці Acquiring3

Генерація ключів для мерчанта

Важливі примітки

Підписання запитів новим приватним ключем (створення x-sign)

Створення x-sign вручну

1. Поле Private key

2. Поле Input

3. Поле Output

4. Параметр x-sign

Створення сесії в зовнішньому еквайрингу | Create session

Проведення оплати | Add payment

Завершення операції | Complete Hold

Повернення заблокованих раніше коштів | Void session

Завершення терміну дії платіжної сесії | Expire session

Запит на отримання статусу сесії | Get status

4. Параметр `x-sign`