Загальні відомості: відмінності між версіями

Поточна версія на 08:24, 15 серпня 2025

Merchant API

(Токенізація з передачею даних картки у запиті

Вступ

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

Заголовки запитів

Для надсилання запиту та отримання відповіді у форматі JSON, необхідно передати такі обов’язкові заголовки у запиті.

--header 'Content-Type: application/json'

--header 'AppId: cd7fde18-15db-4d94-a91b-7cf8edd81209'

--header 'PageId: 3e7bf353-417a-410c-a22e-df8bdcccb760'

--header 'PartnerKey: easypay-test'

--header 'locale: ua'

--header 'Sign: bS+vPOwu1Sif1Iz47Cdh+z1RAi0s6X21C3uU0YNBNWE='

URL

Посилання	Характеристика	Коментарій
`https://merchantapi.easypay.ua`	Production	в т.ч. для надсилання тестових запитів

Налаштування безпеки

Партнер надає IP, з яких будуть здійснюватися запити.

Реєстрація партнера в системі EasyPay

Реєстрація нового торговця передбачає отримання унікального ідентифікатора PartnerKey.

Характеристика параметрів реєстрації

Параметр	Характеристика	Коментарій
`PartnerKey`	унікальний ідентифікатор партнера (продавця) у системі EasyPay.	передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.
`ServiceKey`	ідентифікатор сервісу торговця у системі EasyPay.	магазину чи послуги передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.
`SecretKey`	секретний ключ для формування підпису	відомий лише торговцю та EasyPay передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.
`AppId`	ідентифікатор торгової точки партнера	параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)
`PageId`	ідентифікатор сесії	параметр валідний протягом 20 хв. Для кожного запиту CreateOrder потрібно використовувати унікальний PageID

Тестові параметри

Для тестових запитів використовуються такі параметри:

PartnerKey = easypay-test
ServiceKey = MERCHANT-TEST
SecretKey = test

На даний момент відсутня можливість тестування з використанням фейкових оплат / тестових карток. Платежі тільки реальні, їх можна відмінити в день оплати методом cancelOrder (Скасування платежу)

Тестове середовище

Перед початком використання тестового середовища необхідно надати ір з яких будуть надходити запити, для відкриття доступу. На тестовому середовищі використовуються методи аналогічні Merchant Api. Тестові дані:

PartnerKey:credit-test
SecretKey: credit-test
serviceKey:TEST-CREDIT-PAYMENT - погашення
serviceKey:TEST-CREDIT-PAYMENT - погашення
serviceKey:TEST-CREDIT-TO-CARD - виплата
Надсилання колбеків з Iр: 195.230.131.50

Тестові картки для верифікації/виплат:

Код підтвердження для 2дс при верифікації картки: 123456

Pan	Card.Expire/CVV	Статус виплати
`5167803258208169`	0525/111	Успішна виплата
`4235751329985326`	0525/111	Неуспішна виплата
`4111111111111111`	0525/111	Неуспішна без створення транзакції
`4999999999990011`	0525/111	Успішна виплата з затримкою статусу 5 хв
`4217198608967728`	0525/111	Неуспішна виплата з затримкою статусу 5 хв

Тестові картки для оплати:

Pan	Card.Expire/CVV	Статус виплати
`5168752081922117`	0128/111	Успішна оплата з 3ДС/ або не успішна оплата з 3ДС
`4909150002132451`	0129/111	Успішна 2ДС оплата
`4300380058021820`	0130/111	Не успішна з 3ДС + помилка PAYMENT_ALFABANK_116
`5567217349220669`	0130/111	Успішна оплата з 3ДС/ або не успішна оплата з 3ДС

У разі отримання помилки APPID_NOT_FOUND у відповідь на будь-який метод, необхідно повторити запит createApp до отримання точки ІД.

← Назад
Головна сторінка

Далі → Основні запити та відповіді

@@ Рядок 1: / Рядок 1: @@
+{{APINav}}
+__NOTOC__
+__NOTOC__
 == Вступ ==
-<blockquote style="border-left: 4px solid #007BFF; padding-left: 16px; margin: 1em 0; font-size: 16px;">
+----<blockquote style="border-left: 4px solid #007BFF; padding-left: 16px; margin: 1em 0; font-size: 16px;">
    Протокол призначено для торговців, які є одержувачами платежів. Продавець підписує договір про прийняття платежів або анкету-акцепт до публічної оферти.
 Щоб отримати платежі, ви можете використовувати web, мобільні версії сайтів, а також мобільні програми. У разі використання цього протоколу не здійснюється перевірка даних для ідентифікації замовлення або облікового запису. EasyPay завжди приймає дані, надіслані та створені продавцем.
 </blockquote>
+== Заголовки запитів ==
+----Для надсилання запиту та отримання відповіді у форматі JSON, необхідно передати такі обов’язкові заголовки у запиті.<syntaxhighlight lang="markdown" line="1">
+--header 'Content-Type: application/json'
+--header 'AppId: cd7fde18-15db-4d94-a91b-7cf8edd81209'
+--header 'PageId: 3e7bf353-417a-410c-a22e-df8bdcccb760'
+--header 'PartnerKey: easypay-test'
+--header 'locale: ua'
+--header 'Sign: bS+vPOwu1Sif1Iz47Cdh+z1RAi0s6X21C3uU0YNBNWE='
+</syntaxhighlight>
+== URL ==
+----<table style="border-collapse: collapse; width: 100%; font-family: Roboto, sans-serif; font-weight: 100; font-size: 0.8em; color: #333;">
+    <!-- Перший рядок - заголовок -->
+    <tr>
+      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Посилання</th>
+      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Характеристика</th>
+      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Коментарій</th>
+    <!-- Другий рядок -->
+    <tr>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>https://merchantapi.easypay.ua</code>'''</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">Production</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">в т.ч. для надсилання тестових запитів</td>
+    </tr>
+</table>
+<br>
+== Налаштування безпеки ==
+----Партнер надає IP, з яких будуть здійснюватися запити.
+<br>
+== Реєстрація партнера в системі EasyPay ==
+----Реєстрація нового торговця передбачає отримання унікального ідентифікатора '''PartnerKey'''.
+<br>
+'''Характеристика параметрів реєстрації'''<div style="overflow-x: auto; display: block; width: unset !important; height: auto !important; border: none;">
+  <table style="border-collapse: collapse; width: 100%; font-family: Roboto, sans-serif; font-weight: 100; font-size: 0.8em; color: #333;">
+    <!-- Перший рядок - заголовок -->
+    <tr>
+      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Параметр</th>
+      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Характеристика</th>
+      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Коментарій</th>
+    </tr>
+    <!-- Другий рядок -->
+    <tr>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>PartnerKey</code>'''</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">унікальний ідентифікатор партнера (продавця) у системі EasyPay.</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.</td>
+    </tr>
+    <!-- Третій рядок -->
+    <tr>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>ServiceKey</code>'''</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">ідентифікатор сервісу торговця у системі EasyPay.</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">магазину чи послуги
+передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.
+</td>
+    </tr>
+    <!-- Четвертий рядок -->
+    <tr>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>SecretKey</code>'''</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">секретний ключ для формування підпису</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">відомий лише торговцю та EasyPay
+передається партнеру після реєстрації у системі EasyPay відповідальним менеджером.
+</td>
+    </tr>
+    <!-- П'ятий рядок -->
+    <tr>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>AppId</code>'''</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">ідентифікатор торгової точки партнера </td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">параметр валідний протягом 90 днів. Один і той же AppID може використовуватись для декількох платежів)</td>
+    </tr>
+    <!-- Шостий рядок -->
+    <tr>
+      <td style="border: none; padding-right: 10px; text-align: left;">'''<code>PageId</code>'''</td>
+      <td style="border: none; padding-right: 10px; text-align: left;">ідентифікатор сесії </td>
+      <td style="border: none; text-align: left;">параметр валідний протягом 20 хв. Для кожного запиту CreateOrder потрібно використовувати унікальний PageID</td>
+    </tr>
+  </table>
+<br>
+== Тестові параметри ==
+----Для тестових запитів використовуються такі параметри:<br>
+<br>
+<syntaxhighlight lang="pl">
+PartnerKey = easypay-test
+ServiceKey = MERCHANT-TEST
+SecretKey = test
+</syntaxhighlight>
+<p style="border: 1px solid #4A90E2; background-color: rgba(74, 144, 226, 0.1); padding: 10px; border-radius: 8px; font-family: Arial, sans-serif; font-size: 14px; font-weight: normal; color: #333; position: relative;">
+    На даний момент відсутня можливість тестування з використанням фейкових оплат / тестових карток.
+    Платежі тільки реальні, їх можна відмінити в день оплати методом
+    <span style="background-color: #EDEDED; padding: 2px 5px; border-radius: 4px; font-family: monospace; color: #D63384;">cancelOrder</span>
+ ([[MerchantAPI#Скасування платежу|Скасування платежу]])
+</p>
+=== Тестове середовище ===
+----Перед початком використання тестового середовища необхідно надати ір з яких будуть надходити запити, для відкриття доступу. На тестовому середовищі використовуються методи аналогічні Merchant Api.
+'''Тестові дані:'''<syntaxhighlight lang="markdown" line="1">
+PartnerKey:credit-test
+SecretKey: credit-test
+serviceKey:TEST-CREDIT-PAYMENT - погашення
+serviceKey:TEST-CREDIT-PAYMENT - погашення
+serviceKey:TEST-CREDIT-TO-CARD - виплата
+Надсилання колбеків з Iр: 195.230.131.50
+</syntaxhighlight><br>
+<br>
+'''Тестові картки для верифікації/виплат:'''
+Код підтвердження для 2дс при верифікації картки: 123456
+<table style="border-collapse: collapse; width: 100%; font-family: Roboto, sans-serif; font-weight: 100; font-size: 0.8em; color: #333;"><tr>
+      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Pan</th>
+      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Card.Expire/CVV</th>
+      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Статус виплати </th><tr>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>5167803258208169</code>'''</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">0525/111</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Успішна виплата</td>
+    </tr><tr>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>4235751329985326</code>'''</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">0525/111</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Неуспішна виплата
+</td>
+    </tr><tr>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>4111111111111111</code>'''</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">0525/111</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Неуспішна без створення транзакції
+</td>
+    </tr><tr>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>4999999999990011</code>''' </td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">0525/111 </td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Успішна виплата з затримкою статусу 5 хв</td>
+    </tr><tr>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>4217198608967728</code>'''</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">0525/111 </td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Неуспішна виплата з затримкою статусу 5 хв
+</td>
+    </tr></table>
+<br>
+'''Тестові картки для оплати:'''<table style="border-collapse: collapse; width: 100%; font-family: Roboto, sans-serif; font-weight: 100; font-size: 0.8em; color: #333;"><tr>
+      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Pan</th>
+      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Card.Expire/CVV</th>
+      <th style="border: none; border-bottom: 1px solid #d3d3d3; text-align: center; padding: 8px;">Статус виплати </th><tr>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>5168752081922117</code>'''</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">0128/111</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Успішна оплата з 3ДС/ або не успішна оплата з 3ДС</td>
+    </tr><tr>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">'''<code>4909150002132451</code>'''</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">0129/111</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Успішна 2ДС оплата
+</td>
+    </tr><tr>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;"><code>4300380058021820</code></td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; padding-right: 10px; text-align: left;">0130/111</td>
+      <td style="border: none; border-bottom: 1px solid #d3d3d3; text-align: left;">Не успішна з 3ДС + помилка PAYMENT_ALFABANK_116
+</td>
+    </tr><tr><td><code>'''5567217349220669'''</code></td><td>0130/111</td><td>Успішна оплата з 3ДС/ або не успішна оплата з 3ДС</td></tr></table>
+<br>
+<p style="border: 1px solid #4A90E2; background-color: rgba(74, 144, 226, 0.1); padding: 10px; border-radius: 8px; font-family: Arial, sans-serif; font-size: 14px; font-weight: normal; color: #333; position: relative;">
+    У разі отримання помилки <span style="background-color: #EDEDED; padding: 2px 5px; border-radius: 4px; font-family: monospace; color: #D63384;">APPID_NOT_FOUND</span>
+    у відповідь на будь-який метод, необхідно повторити запит
+    <span style="background-color: #EDEDED; padding: 2px 5px; border-radius: 4px; font-family: monospace; color: #D63384;">createApp</span>
+    до отримання точки ІД.
+</p>
+<br>
+<div style="width: 100%; display: flex; justify-content: space-between; gap: 16px; box-sizing: border-box; padding: 8px 0;">
+  <!-- Ліва кнопка -->
+  <div style="
+    position: relative;
+    flex: 1;
+    min-width: 150px;
+    background: rgba(135, 206, 250, 0.1);
+    padding: 8px 14px;
+    border-radius: 8px;
+    border: 1px solid #007BFF;
+    color: #007BFF;
+    font-weight: bold;
+    font-size: 1em; /* пропорційний розмір */
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    text-align: center;
+    cursor: pointer;
+  ">
+<!-- Текст у кутку --><span style="position: absolute; top: 6px; left: 8px;">← Назад</span>
+    <!-- Основний текст -->
+<br>
+[[Головна сторінка]]
+</div>
+  <!-- Права кнопка -->
+  <div style="
+    position: relative;
+    flex: 1;
+    min-width: 150px;
+    background: rgba(135, 206, 250, 0.1);
+    padding: 8px 14px;
+    border-radius: 8px;
+    border: 1px solid #007BFF;
+    color: #007BFF;
+    font-weight: bold;
+    font-size: 1em; /* пропорційний розмір */
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    text-align: center;
+    cursor: pointer;
+  ">
+<span style="position: absolute; top: 6px; right: 8px;">Далі →</span>
+    <!-- Основний текст -->
+<span>[[Основні запити та відповіді]]</span>
+  </div>
+</div>