Fiscalization: відмінності між версіями

← Попереднє редагування Наступне редагування →

ВізуальнийВікірозмітка

Версія за 09:59, 20 січня 2026

1. Попередні умови

Для фіскалізації транзакцій мерчант повинен:

Бути зареєстрованим у сервісі Checkbox: https://checkbox.ua
Мати в Checkbox:
- зареєстровану касу
- створеного касира

2. Дані, які потрібно надати EasyPay

Після реєстрації в Checkbox необхідно надіслати менеджеру EasyPay на email:

Ключ ліцензії каси (licenseKey)

PIN-код касира

serviceKey, з якого будуть фіскалізуватися транзакції

⚠️ Без передачі цих даних фіскалізація працювати не буде.

3. Робота зі змінами

Зміна відкривається автоматично разом із першою фіскалізованою транзакцією за день
Зміна автоматично закривається о 23:45

4. Загальна схема роботи

Мерчант створює замовлення (createOrder) з параметрами фіскалізації
EasyPay ініціює фіскалізацію в сервісі Checkbox
Checkbox формує фіскальний чек
Статус фіскалізації та URL чека:
- надсилаються в callback, або
- доступні через метод fiscalization/check
У разі повернення коштів використовується метод CancelOrder

5. Створення платежу з фіскалізацією

Для фіскалізації транзакції в методі:

POST /api/merchant/createOrder

потрібно передати обʼєкт fiscalization.

5.1. Приклад запиту `createOrder`

{
"order": {
"serviceKey": "MERCHANT-TEST-XXXX",
"orderId": "Fiscalization29",
"description": "Test for fiscalization",
"amount": 3,
"isOneTimePay": false,
"additionalItems": {
"Merchant.UrlNotify": "http://notifysigncheckexample.com"
}
},
"fiscalization": {
"licenseKey": "test8d2f483fafef",
"receiptType": "Url",
"receipt": {
"goods": [
{
"good": {
"code": "9999",
"name": "Wine",
"price": 1.5
},
"quantity": 2
}
],
"payments": [
{
"type": "CASHLESS",
"value": 3
}
]
}
}
}

6. Обʼєкт `fiscalization`

6.1. Загальна структура

Поле	Тип	Обов'язкове	Опис
licenseKey	string	✅	Ключ ліцензії каси Checkbox
receiptType	string	✅	Завжди `"Url"`
receipt	object	✅	Дані фіскального чека

6.2 receipt

Поле	Тип	Обовʼязкове	Опис
goods	array	✅	Перелік товарів
payments	array	✅	Інформація про оплату

6.3 goods[ ]

Поле	Тип	Обовʼязкове	Опис
good.code	string	✅	Код товару
good.name	string	✅	Назва товару
good.price	decimal	✅	Ціна за одиницю
quantity	decimal	✅	Кількість (до 3 знаків після коми)

Валідація: price × quantity = value у payments

6.4 payments[ ]

Поле	Тип	Обовʼязкове	Опис
type	string	✅	Завжди `"CASHLESS"`
value	decimal	✅	Сума платежу

7. Перевірка статусу фіскалізації

POST /api/merchant/fiscalization/check

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

{
"orderId": "Fiscalization29",
"transactionid": 111111,
"serviceKey": "MERCHANT-TEST-XXXX"
}

Можливі статуси

Accepted — фіскалізація успішна
InProcess — в обробці
Declined — помилка

8. Повернення коштів (`CancelOrder`)

Часткове повернення

Умови:

транзакція була фіскалізована
повертається частина товарів

Особливості:

обʼєкт fiscalization обовʼязковий
передаються тільки товари та суми, які повертаються

Повне повернення

повертається вся сума платежу
обʼєкт fiscalization можна не передавати

@@ Рядок 4: / Рядок 4: @@
 * Бути зареєстрованим у сервісі '''Checkbox''': https://checkbox.ua
-* Мати в '''Checkbox''':
+* Мати в Checkbox:
-** зареєстровану '''касу'''
+** зареєстровану касу
-** створеного '''касира'''
+** створеного касира
 <br>
 == 2. Дані, які потрібно надати EasyPay ==
-----Після реєстрації в Checkbox мерчант повинен надіслати менеджеру EasyPay на email такі дані:
+----Після реєстрації в Checkbox необхідно '''надіслати менеджеру EasyPay на email''':
+'''Ключ ліцензії каси (licenseKey)'''
+[[Файл:Ключ ліцензії.png|центр|міні|600x600пкс]]
+'''<br>
-'''Ключ ліцензії каси''' (<code>licenseKey</code>)
+'''PIN-код касира'''
-[[Файл:Ключ ліцензії.png|центр|міні|600x600пкс]]
-<br>'''PIN-код касира'''
-[[Файл:Пін код.png|центр|міні|600x600пкс]]
+'''[[Файл:Пін код.png|центр|міні|600x600пкс]]
+'''serviceKey''', з якого будуть фіскалізуватися транзакції
-'''serviceKey''', з якого потрібно фіскалізувати транзакції. Без передачі цих даних фіскалізація працювати не буде.
+⚠️ Без передачі цих даних фіскалізація працювати не буде.
+<br>
 == 3. Робота зі змінами ==
@@ Рядок 27: / Рядок 30: @@
-=== 4. Загальна схема роботи ===
+== 4. Загальна схема роботи ==
 ----[[Файл:Схема.png|центр|міні|400x400пкс]]
-<br>
 # Мерчант створює замовлення (<code>createOrder</code>) з параметрами фіскалізації
 # EasyPay ініціює фіскалізацію в сервісі Checkbox
@@ Рядок 40: / Рядок 43: @@
 == 5. Створення платежу з фіскалізацією ==
-----Для фіскалізації транзакції в методі: <code>POST /api/merchant/createOrder</code> потрібно передати обʼєкт <code>fiscalization</code>.
+----Для фіскалізації транзакції в методі:
+<code>POST /api/merchant/createOrder</code>
+потрібно передати обʼєкт <code>fiscalization</code>.
-==== 5.1. Приклад запиту <code>createOrder</code> ====
+=== 5.1. Приклад запиту <code>createOrder</code> ===
-<syntaxhighlight lang="json">
+----<syntaxhighlight lang="json">
+{
+"order": {
+"serviceKey": "MERCHANT-TEST-XXXX",
+"orderId": "Fiscalization29",
+"description": "Test for fiscalization",
+"amount": 3,
+"isOneTimePay": false,
+"additionalItems": {
+"Merchant.UrlNotify": "http://notifysigncheckexample.com"
+}
+},
+"fiscalization": {
+"licenseKey": "test8d2f483fafef",
+"receiptType": "Url",
+"receipt": {
+"goods": [
+{
+"good": {
+"code": "9999",
+"name": "Wine",
+"price": 1.5
+},
+"quantity": 2
+}
+],
+"payments": [
 {
-  "order": {
+"type": "CASHLESS",
-    "serviceKey": "MERCHANT-TEST-XXXX",
+"value": 3
-    "orderId": "Fiscalization29",
+}
-    "description": "Test for fiscalization",
+]
-    "amount": 3,
+}
-    "isOneTimePay": false,
+}
-    "additionalItems": {
-      "Merchant.UrlNotify": "http://notifysigncheckexample.com"
-    }
-  },
-  "fiscalization": {
-    "licenseKey": "test8d2f483fafef",
-    "receiptType": "Url",
-    "receipt": {
-      "goods": [
-        {
-          "good": {
-            "code": "9999",
-            "name": "Wine",
-            "price": 1.5
-          },
-          "quantity": 2
-        }
-      ],
-      "payments": [
-        {
-          "type": "CASHLESS",
-          "value": 3
-        }
-      ]
-    }
-  }
 }
 </syntaxhighlight>
-== 6. Обʼєкт fiscalization — опис полів ==
+== '''6. Обʼєкт <code>fiscalization</code>''' ==
 ----
-=== '''6.1 Загальна структура''' ===
+=== '''6.1. Загальна структура''' ===
 <table style="width:100%; border-collapse:collapse; border-spacing:0;">
      <tr style="border-bottom:1px solid #e6e6e6;">
@@ Рядок 117: / Рядок 121: @@
 </table>
 <br>
+====  '''6.2 receipt''' ====
-=== '''6.2 receipt''' ===
 <!-- 6.2 Обʼєкт receipt -->
 <table style="width:100%; border-collapse:collapse; border-spacing:0;">
      <tr style="border-bottom:1px solid #e6e6e6;">
@@ Рядок 141: / Рядок 143: @@
      </tr>
 </table>
 <br>
+==== '''6.3 goods[  ]''' ====
-=== '''6.3 goods[ ]''' ===
+<!-- 6.3 Масив goods[] -->
 <table style="width:100%; border-collapse:collapse; border-spacing:0;">
      <tr style="border-bottom:1px solid #e6e6e6;">
@@ Рядок 176: / Рядок 179: @@
      </tr>
 </table>
-<br>Валідація - '''price × quantity = value у payments'''
+<br>
+'''Валідація:'''
+price × quantity = value у payments
-==== '''6.4 payments[ ]''' ====
+====  '''6.4 payments[  ]''' ====
-<!-- 6.4 Масив payments[] -->
+<table style="width:100%; border-collapse:collapse; border-spacing:0;">
-<table style="width:100%; border-collapse:collapse; border-spacing:0;"><tr style="border-bottom:1px solid #e6e6e6;">
+    <tr style="border-bottom:1px solid #e6e6e6;">
        <th style="text-align:left; padding:12px 16px;">Поле</th>
        <th style="text-align:left; padding:12px 16px;">Тип</th>
        <th style="text-align:left; padding:12px 16px;">Обовʼязкове</th>
        <th style="text-align:left; padding:12px 16px;">Опис</th>
-     </tr><tr style="border-bottom:1px solid #efefef;">
+     </tr>
+    <tr style="border-bottom:1px solid #efefef;">
        <td style="padding:16px;">type</td>
        <td style="padding:16px;">string</td>
        <td style="padding:16px;">✅</td>
-       <td style="padding:16px;">Завжди <code style="background:#f3f3f3; padding:2px 6px; border-radius:6px;">CASHLESS</code>
+       <td style="padding:16px;">Завжди <code style="background:#f3f3f3; padding:2px 6px; border-radius:6px;">"CASHLESS"</code>
        </td>
      </tr>
@@ Рядок 197: / Рядок 203: @@
        <td style="padding:16px;">✅</td>
        <td style="padding:16px;">Сума платежу</td>
-     </tr></table>
+     </tr>
+</table>
 <br>
-== Перевірка статусу фіскалізації ==
+== 7. Перевірка статусу фіскалізації ==
-<code>POST /api/merchant/fiscalization/check</code>
+----<br>
+<p style="border: 1px solid #9ACD32; background-color: rgba(192, 255, 192, 0.5); padding: 10px; border-radius: 8px; font-family: Arial, sans-serif; font-size: 14px; font-weight: normal; position: relative; padding-left: 80px;">
+    <span style="position: absolute; top: 10px; left: 10px; background-color: #006400; color: white; padding: 2px 12px; border-radius: 4px; font-size: 14px; font-weight: bold;">POST</span>
+    <span style="margin-left: 5px; font-weight: bold; font-size: 16px;">/api/merchant/fiscalization/check</span>
+</p>
 === Приклад запиту ===
 <syntaxhighlight lang="json">
@@ Рядок 217: / Рядок 227: @@
 * '''<code>InProcess</code>''' — в обробці
 * '''<code>Declined</code>''' — помилка
+<br>
 == 8. Повернення коштів (<code>CancelOrder</code>) ==
@@ Рядок 223: / Рядок 233: @@
 === Часткове повернення ===
-Умови:
+'''Умови:'''
 * транзакція була фіскалізована
 * повертається частина товарів
+'''<br>
-Особливості:
+'''Особливості:'''
 * обʼєкт <code>fiscalization</code> '''обовʼязковий'''