Fiscalization

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

---

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

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

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

---

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

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

PIN-код касира

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

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

3. Робота зі змінами та часові обмеження

---

3.1 Автоматична робота зі змінами

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

3.2 Налаштування автозакриття каси в Checkbox

У кабінеті Checkbox необхідно обовʼязково встановити автозакриття каси на 23:45 (не раніше).

EasyPay додатково виконує автоматичне закриття кас о 23:40, але налаштування в кабінеті Checkbox використовується як додатковий запобіжник для коректної роботи фіскалізації.

3.3 Період перезміни (23:30 – 00:00)

У проміжок часу з 23:30 до 00:00 в EasyPay та Checkbox відбувається перезміна.

У цей період:

• транзакції та чеки можуть перебувати в статусі обробки
• фактична фіскалізація таких транзакцій виконується вже новим днем
• це є штатною поведінкою системи та не потребує дій з боку Мерчанта

3.4 Обмеження на ручні дії в Checkbox

Під час роботи з фіскалізацією через EasyPay:

• заборонено виконувати будь-які ручні дії з касою або чеками через:
  • Checkbox.Kasa
  • Checkbox Manager
• уся фіскалізація, відкриття/закриття змін та обробка чеків виконується EasyPay автоматично

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

---

1. Мерчант створює замовлення (createOrder) з параметрами фіскалізації
2. EasyPay ініціює фіскалізацію в сервісі Checkbox
3. Checkbox формує фіскальний чек
4. Статус фіскалізації та URL чека:
   • надсилаються в callback, або
   • доступні через метод fiscalization/check
5. У разі повернення коштів використовується метод 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 можна не передавати