/
Checkout NovaPay

Checkout NovaPay

Загальний опис

Checkout NovaPay – це новий сервіс для онлайн-торгівлі, який поєднує платіжний та логістичний функціонал в одному рішенні. Іншими словами, клієнт може одночасно оплатити товар або оформити післяплату і оформити доставку прямо на сайті торговця.

Переваги Checkout NovaPay

Для платника (клієнт мерчанта) – простіший і швидший процес покупки:

  • 🔄 Автоматичне підвантаження даних клієнта, таких як: ПІБ, улюблені способи доставки та оплати покупця (якщо вони є в NovaPay).

  • 📍 Можливість обрати відділення або інший спосіб отримання. Якщо дані вже є в системі – NovaPay заповнює їх автоматично.

  • 💳 Доступність різних способів оплати (карта, Google/Apple Pay, рахунок NovaPay, післяплата).

Для торговця (мерчанта) – легке підключення платіжного та логістичного модуля без складної інтеграції:

  • ⚡ Прискорений процес checkout підвищує конверсію.

  • ✅ Мінімізація помилок завдяки автоматичному заповненню даних клієнта.

  • 📦 Надає інформацію для оформлення логістичної операції та може створити ЕН замість мерчанта.

Для NovaPay – розширення екосистеми та залучення нових клієнтів через торговців:

  • 🌐 Розширення екосистеми та залучення нових клієнтів через торговців.

Термінологія

  • Кнопка NovaPay – метод оплати NovaPay з переходом Платника у додаток МД NovaPay.

  • iframe NovaPay/ iframe – платіжна сторінка NovaPay.

  • Платник – особа яка планує здійснити купівлю товару/послуги у торговця через WEB|APP|чат-бот торговця.

  • МД NovaPay – мобільний додаток NovaPay.

  • Експрес-накладна (ЕН) – це унікальний код з 14 цифр, який присвоюється Новою поштою кожному відправленню.

  • Торговець (мерчант) – ЮО/ФОП, що здійснюють підприємницьку діяльність та мають підписаний договір з NovaPay на переказ коштів.

  • Скасування (Void) – це скасування платежу в той же день, коли він був здійснений (до 23:50) або до зарахування коштів на рахунок мерчанта. Тобто кошти не списуються остаточно, і операція анулюється ще до завершення обробки в платіжних системах.

image-20251218-132749.png

Процес оплати

Оплата при передачі номера телефону торговцем

  1. Платник натискає "Купити через NovaPay" на сайті.

  2. Торговець надсилає запит до NovaPay API, передаючи номер телефону платника.

  3. NovaPay перевіряє базу даних та, якщо платник є, автоматично підтягує його ПІБ, телефон та інші дані у checkout.

  4. Платник перевіряє або змінює дані, обирає спосіб доставки (відділення, поштомат, кур’єр).

  5. Вибирає метод оплати:

    1. Google Pay / Apple Pay

    2. Введення картки

    3. Кнопка NovaPay (оплата у мобільному додатку NovaPay)

    4. Оплата у відділенні (якщо товар з післяплатою)

  6. NovaPay може автоматично створювати ЕН у системі Нової пошти, однак мерчант має можливість обрати режим без автоматичного формування ЕН.

  7. Торговцю передаються: платіж, ЕН а також інформація про платника й обрану точку доставки.

  8. Торговець відправляє товар у вибране платником місце.

Оплата без передачі номера телефону (введення вручну)

  1. Платник натискає "Купити через NovaPay".

  2. NovaPay відкриває checkout без автоматично підставлених даних.

  3. Платник вводить ПІБ, номер телефону, вибирає спосіб доставки.

  4. Якщо платник має акаунт у NovaPay, він може пройти верифікацію через QR-код або номер телефону для автоматичного заповнення форми.

  5. Подальші етапи збігаються з попереднім варіантом: вибір оплати, створення ЕН, передача даних торговцю.

Інтеграція Checkout NovaPay

Протестувати API запити можна за посиланням: https://novapay.readme.io/reference/checkout

Крок 1: Автентифікація

Цей API використовує формат JSON для отримання тіла запитів і передачі відповідей.

API використовує підписи RSA (передаються в заголовку x-sign) для перевірки походження запиту. Підпис створюється на основі тіла запиту, шифрується у форматі base64 і перевіряється аналогічним чином. Для отримання доступу до API зв’яжіться з нашою службою підтримки, надавши свій відкритий ключ RSA.

Якщо мерчант обирає автоматичне створення ЕН, він повинен надати свій API-ключ Нової Пошти. Це необхідно для того, щоб ЕН формувалася від імені мерчанта та відображалась у його кабінеті Нової Пошти.

Генерація підписів

Алгоритм створення підпису – SHA-256
Рекомендований ключ: зашифрований паролем, довжина 2048 біт.

Ключі

Merchant ID

merchant_id = "надається NovaPay при реєстрації"

 

 

 

echo -n '{ "merchant_id": 1, "client_first_name": "Іванов", "client_last_name": "Іван", "client_phone": "+380982850654" }' | openssl dgst -sha256 -sign key.pem | openssl enc -base64

 

 

 

 

-----BEGIN RSA PRIVATE KEY----- MIIEowIBAAKCAQEA7YQwYDqNbDIbUXZL2HYvZX6wi59DgsMlYjwpoSgHvn0RTnWl /uR2sIJ9tquYh5Ya+TtUhzrc0N6mZPTLUuyK4qKq2NJaG2Xdr2M5LhMjF46llWkD qMW/CcMdVTTE4b1FxOOXURNmZ7nWCchuiVU9nm0K5qYAQpPJFzwg9uDljYgcMp3N 9L1WaiyzIqJqL4R9L39j2t4yOUb4m44xyjujGViHm5lQBNklkOcsxMlb0T3AVNcA +KckSl32TdvvmSx9BwzK4SDqQAR8MtKA4hbeA3KGCflRlJKv5KcCpPOOzaoUlaTN OLmJIhl0/VjpsKqLNMQOyRSkpRVCFhgp6sO/ewIDAQABAoIBAEBaqbTZCIqBRQ+c as56rzrjybf67hLXByEHxgvJSdfeETtd+x0GD/ahVKiS8+AA1swivDNrynq5aQI/ pXuRZcwkYQAgdpOn1Rn5W3vVaZOvbcP+0SQAeFOPzznP82xqmSXQuKYaCIwgORMr gG+rbeeoCeUWo0lmu3yVKSVbKDdhXQqQB0EiC1rZoEKr9iKOAS5Hvi7pU/bxpH3a xEGh8ov8E89UtubiIL+LhqsN5dVgowWiaPbA945z497VgjAu+/I2jQ6HhuyPNhK1 SMa0LExXN5xmzF3WJ8ofVMS/hJbLYWgidfUi+MYCgm3W1YtpnNFBKDiDa83cEWqo r5/GJYECgYEA9w9yXkAsUe3c3Qw1lGSZJNzSlbwCKA4wMaiLhsZWfyLrkzzQnY+t tu+5Tfa3EU3bLof3juwSBSVwYcb3ZJWGeVURYQwO3ZirZQ3xxEQTI5FTCuJRPMsf 8oiq6NxgZrK3NdtmtecH6+IvrO/J3UPKc8a+iop3zR2tTU4rs2jAbMECgYEA9hxV yAGXZavNHfrqIn9NCZLySaYrMKSZj36xCcksHK7do77OmsqAp8wQuxYIPoABNO/8 bd2ry33b8Zd3dv5iRI3GMmmrxQ7yDviKeUptKKBZsm9CWEcGnmNOia+ZyJbRl9Fp jnrtUNOCQxwz144eTAKLV2JUD6Kgfr1ee1EDbzsCgYEA7Q0zLV/hppLWUno+hq2n i4kdvXHxl8FVWLBhf+WaZM56voGhoSyU/2wwnq/Uo5PSdGkdjVLRT4LGu+qOwUH/ DzgiPr21HcY43fNtQGYY/w2XYmAYln5HnwynAFtDXAaqZ9CmUm7kWN5j5EkHpXhA LqpJdOC7ZmHNQNl6cOBXkYECgYA7Qi9VbSyrCmblJRljHQvLllpIaX5UxA1Fg9fU 5197uI8dckAE/WVlAbm1kmSByAiCWpaJTaqj4LYowbO+LxoyL4DdepwlYqfd+vI8 qjMGaTWvxSJQZyms0XSDqoh4x/fHemDUMb0ajRL8XboN2OZqnuI2NDLRYPMMEUTC pIsTKQKBgGqbsr+cn+Ny2cPO8KCx1y6WWrT2X5k286rjAMGxNNG/aNqejpTixAaJ dA8rov0FcJ03MOhw69XYxkVGpLqWhtMjiWSYuHJBSspvp0QcD9nQykXDLfO7FeeA p8WexL0FZSkNlkMbcpMI6U0g51cwacZeGA3qXoKWzWfz2Brmom90 -----END RSA PRIVATE KEY-----
-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw1FeLVQlCYMnxVMPwhHA AYik6KGfYz0GJW0SP4dBs6XQ2Ap2kP0X3K5WtJNnPehiWf7jJz9XH2Xh/17t37kZ KXGEdWYtPUAWQItLGSIwmPMau+YBFFvLD8OReFhFXc6sjReSPJSFV8KDtOP7By9u +KxYqZTVqPxCeYXHOzT7vtDJBJDLbe0pJ3B3wRihMEuHP54X4zqEAi/vbqArhHDD O07FZpQ3PA/Fkgj8jMTUxU3LxmIIkNIuLz+Ze/PxL88qvRkRoHd73agYSs5bVdCg urGUs2hGFQap4KiyR0TRtaJujM715y1gjVFN7Khkkol/dJaHRqxUaZv3dlL+RMXG /wIDAQAB -----END PUBLIC KEY-----

Крок 2: Створення чекаут-сесії | Create checkout session

Мерчант створює checkout-сесію, передаючи необхідні дані про замовлення.

Метод POST

URL ендпоінту на проді https://api-ecom.novapay.ua/v1/checkout/session

Параметри запиту

Параметр

Тип

Обов’язковий

Опис

Параметр

Тип

Обов’язковий

Опис

merchant_id

string

✅ Так

ID мерчанта, від імені якого створюється сесія.

callback_url

string

✅ Так

Після оплати ми надішлемо postback на цей url з інформацією про сесію.

success_url

string

❌ Ні

Після успішної оплати клієнт може натиснути кнопку і перейти за цим посиланням.

fail_url

string

❌ Ні

Після невдалої оплати клієнт може натиснути кнопку і перейти за цим посиланням.

client_phone

string

❌ Ні

Номер телефону з кодом країни.

create_express_waybill

boolean

❌ Ні

Ознака чи потрібно створювати електронну накладну:

true – створювати ЕН (якщо мерчант обирає автоматичне створення ЕН, він повинен надати свій API-ключ Нової Пошти).

false (значення за замовчуванням) – не створювати ЕН.

delivery

object

❌ Ні

Дані про посилку.

Обов'язково до заповнення лише якщо create_express_waybill: true.

volume_weight

float

❌ Ні

Об’ємна вага посилки.

Обов'язково до заповнення лише якщо create_express_waybill: true.

weight

float

❌ Ні

Фізична вага посилки. Обов'язково до заповнення лише якщо create_express_waybill: true.

{ "delivery": { "volume_weight": 0.0004, "weight": 0.1 }, "merchant_id": "1", "callback_url": "https://example.com", "client_phone": "+380982850620" }
{ "delivery": { "volume_weight": 0.0004, "weight": 0.1 }, "create_express_waybill": true, "merchant_id": "1", "callback_url": "https://example.com", "client_phone": "+380982850620" }
{ "create_express_waybill": false, "merchant_id": "1", "callback_url": "https://example.com", "client_phone": "+380982850620" }
{ "id": "a82ce764-2810-46b0-ace1-b02d7a2706fa", "metadata": { "key": "value" } }

Параметр

Тип

Обов’язковий

Опис

Параметр

Тип

Обов’язковий

Опис

id

string

✅ Так

Унікальний ідентифікатор новоствореної сесії.

metadata

object

❌ Ні

Додаткові метадані сесії.

Крок 3: Додавання товарів у кошик та отримання посилання на оплату | Add checkout payment

Метод POST

URL ендпоінту на проді https://api-ecom.novapay.ua/v1/checkout/payment
Параметри запиту

Параметр

Тип

Обов’язковий

Опис

Параметр

Тип

Обов’язковий

Опис

merchant_id

string

✅ Так

ID мерчанта, від імені якого створена сесія.

session_id

string

✅ Так

Ідентифікатор сесії, отриманий у відповіді на запит "Create checkout session".

amount

float

✅ Так

Загальна сума замовлення.

external_id

string

❌ Ні

Ідентифікатор замовлення в системі мерчанта (для реєстрів).

use_hold

boolean

❌ Ні

Параметр двоетапної оплати (утримати кошти та підтвердити). Якщо не вказати цей параметр, значення буде «false». Значення «true» вказується, якщо використовується параметр доставки.

identifier

string

❌ Ні

Необов'язковий параметр для створення платежу отримувачу, який відрізняється від власника мерчанта (ЄДРПОУ).

products

array

❌ Ні

Масив товарів у замовленні.

description

string

❌ Ні

Назва або опис товару.

count

float

✅ Так (якщо є products)

Кількість одиниць товару.

price

float

✅ Так (якщо є products)

Ціна за одиницю.

image

string

❌ Ні

URL-зображення товару.

Після цього платник бачить frame checkout NovaPay та проводить оплату.

{ "use_hold": true, "merchant_id": "1", "session_id": "9b230f39-cb7c-449a-8720-a6e4f98eb57b", "amount": 544.25, "products": [ { "count": 2, "price": 100.25, "image": "https://i.pinimg.com/736x/68/e5/24/68e52437158ced28ada0afc77582eb3f.jpg", "description": "Пальто" } ] }
{ "id": "120190791925", "url": "https://qecom.novapay.ua/checkout/pay?sid=9b230f39-cb7c-449a-8720-a6e4f98eb57b" }

Параметри відповіді

Параметр

Тип

Обов’язковий

Опис

Параметр

Тип

Обов’язковий

Опис

id

string

✅ Так

Унікальний ідентифікатор операції додавання товарів.

url

string

✅ Так

Посилання на сторінку оплати замовлення для користувача.

Крок 4: Отримання статусу платежу та створеної ЕН в Новій Пошті | Checkout postbacks

Після оплати NovaPay надсилає postback на callback_url, вказаний при створенні сесії.

Є три сценарії отримання postback:

  1. Postback після оплати (якщо платник одразу сплатив замовлення).

  2. Postback після створення ЕН.

  3. Postback із причиною невдалого створення ЕН.

{ "id": "f1c86ec3-45ff-4bde-a428-37f49bcde530", "status": "paid", "paytype": "applepay", "created_at": "2025-03-10T15:56:29.169+02:00", "metadata": { "lol": "kek", "marketing_block_en": "Get bonus with visa card!", "marketing_block_uk": "Оплачуй карткою Visa та отримуй бонус!Оплачуй карткою Visa та отримуй бонус!" }, "client_first_name": "Іван", "client_last_name": "Іваненко", "client_patronymic": "Іванович", "client_phone": "+380111111111", "external_id": null, "amount": 53, "delivery": { "recipient_city": "526b41b7-f344-48ad-becf-17544ff460e5", "recipient_warehouse": "526b41b7-f344-48ad-becf-17544ff460e6", "recipient_phone": "+380222222222", "recipient_last_name": "Андрієнко", "recipient_first_name": "Андрій", "recipient_patronymic": "Андрійович" }, "products": [ { "count": 1, "image": "https://i.pinimg.com/736x/a3/b9/ca/a3b9cab8583db63b6eadcd7e9746cba6.jpg", "price": 17, "description": "Заліпуха" }, { "count": 2, "image": "https://i.pinimg.com/736x/68/e5/24/68e52437158ced28ada0afc77582eb3f.jpg", "price": 18, "description": "Плащ-пальто" } ] }

Параметри, що містить postback після оплати:

Параметр

Тип

Обов’язковий

Опис

Параметр

Тип

Обов’язковий

Опис

id

string

✅ Так

Унікальний ідентифікатор сесії.

status

string

✅ Так

Статус оплати (paid, holded тощо).

paytype

string

✅ Так

Тип оплати (cash_on_delivery, card, applepay тощо).

created_at

string (ISO8601)

✅ Так

Дата та час створення операції.

metadata

object

❌ Ні

Додаткові мета-дані сесії.

lol

string

❌ Ні

Додаткове значення.

marketing_block_en

string

❌ Ні

Маркетинговий блок англійською.

marketing_block_uk

string

❌ Ні

Маркетинговий блок українською.

client_first_name

string

✅ Так

Ім’я клієнта.

client_last_name

string

✅ Так

Прізвище клієнта.

client_patronymic

string

❌ Ні

По батькові клієнта.

client_phone

string

✅ Так

Номер телефону клієнта.

external_id

string | null

❌ Ні

Зовнішній ідентифікатор замовлення.

amount

float

✅ Так

Сума замовлення.

delivery

object

✅ Так

Інформація про доставку.

recipient_city

string

✅ Так

Ідентифікатор міста отримувача.

recipient_warehouse

string

✅ Так

Ідентифікатор відділення отримувача.

recipient_phone

string

✅ Так

Телефон отримувача.

recipient_last_name

string

✅ Так

Прізвище отримувача.

recipient_first_name

string

✅ Так

Ім’я отримувача.

recipient_patronymic

string

❌ Ні

По батькові отримувача.

products

array of objects

In NovaPay We Trust