Підключення програмного РРО
Як налаштувати роботу ПРРО
Зареєструйте касу в нашого партнера-провайдера ПРРО
Доступні сервіси ПРРО
Наразі доступний один сервіс — Cash DeskВнесіть нові параметри в API-запит
Додатково до стандартного набору параметрів платіжного запиту, необхідно передавати більше даних про товар для всіх платежів та повернень: методи purchase, auth, capture, refund.
Parameter | Type | Required | Description |
---|---|---|---|
products.id | UUID | ✅ | Унікальний ідентифікатор товару |
products.name | String | ✅ | Назва продукту |
products.amount | Number | ✅ | Вартість за одиницю товару/роботи/послуги |
products.qty | Number | ✅ | Кількість (загальний amount платежу = product.qty * product.amount) |
products.unit | String | ✅ | Одиниця вимірювання (допустимі значення kg, m, pc, l) |
products.bar_code | String | Штрих-код товару (опційний для фіскалізації, але обов’язковий для програми “Національний кешбек”) | |
customer_email | String | Електронна пошта платника (є опційним параметром у випадку, якщо її введення є обов’язковим на чекауті). Обовʼязковий, якщо products.fiscalReceiptDelivery = “email” | |
customer_phone | String | Мобільний номер платника. Обовʼязковий, якщо products.fiscalReceiptDelivery = “viber” або “sms” | |
products.taxes.type | String | Тип податку (допустимі значення vat, non-vat). Якщо субʼєкт господарювання не є платником ПДВ має передаватися значення non-vat | |
products.taxes.prc | Number | Податкова ставка % (допустимі значення 0, 7, 14, 20) | |
products.fiscalReceiptDelivery | String | ✅ | Визначає спосіб, за допомогою якого фіскальний чек буде доставлений покупцю. Допустимі значення: email, viber, sms, none . Залежно від переданого значення, обов'язковими можуть бути параметри customer_phone або customer_email |
При роботі через платіжний віджет необхідно використовувати інші параметри фіскалізації.
Приклад Body запиту на Tranzzo:
{
"pos_id": "00000000-0000-0000-0000-000000000000",
"mode": "direct",
"method": "purchase",
"amount": 100,
"currency": "UAH",
"cc_number": "4111111111111111",
"exp_month": 12,
"exp_year": 24,
"card_cvv": "123",
"order_id": "123456789",
"description":"Опис товару",
"payway": "cc",
"order_3ds_bypass": "supported",
"customer_email": "[email protected]",
"customer_phone": "+38(066) 123-45-67",
"products": [{
"id": "1",
"name": "product name",
"unit": "pc",
"bar_code":"4876534567183",
"amount": 50,
"taxes": [{"type":"vat", "prc": 20}],
"qty": 2,
"fiscalReceiptDelivery": "email"
}],
"server_url": "http://callback-stub:9000/consume"
}
У разі наявності помилки в одному з параметрів, відповідальних за дані про продукт, у відповідь буде отримано помилку з інформацією про конкретне поле, який містить недопустиме значення.
Приклад такої відповіді:
{
"message": "Invalid products provided",
"args": [
{
"field_name": "products[0].name",
"violation": "..."
},
{
"field_name": "products[0].unit",
"violation": "..."
},
{
"field_name": "products[1].name",
"violation": "..."
},
{
"field_name": "products[1].unit",
"violation": "..."
},
{
"field_name": "products[0].id",
"violation": "..."
},
{
"field_name": "products[1].id",
"violation": "..."
},
{
"field_name": "products",
"violation": "..."
}
]
}
Обов’язково внесіть зміни до API-інтеграції перш ніж переходити до наступного кроку. Якщо ви увімкнете ПРРО до того, як внести зміни у API-запит, то платежі не будуть проходити через відсутність обов'язкових параметрів.
Підключіть ПРРО через мерчант-портал
Відкрийте загальні налаштування мерчантського облікового запису та оберіть пункт ПРРО.
Натисніть кнопку Нова конфігурація.
Заповніть форму:
- Імʼя конфігурації: будь-яке значення на ваш вибір.
- Надавач послуг: провайдер ПРРО, в якому ви зареєстрували касу (наразі доступний тільки Cash Desk).
- Ідентифікатор каси (ПРРО ID):
приклад даних із Cash Desk параметрів"num_fiscal": “100000000000”
- API-токен із сервісу-провайдера ПРРО:
приклад даних із Cash Desk“api_token” : "00000000-0000-0000-0000-000000000000
- Область застосування: оберіть зі списку потрібну юридичну особу чи ФОП.
- Переведіть в активне положення перемикач “Увімкнути використання ПРРО при проведення платежів”. Має виглядати як на скріншоті нижче.
Перевірте дані та відправте форму.
Після відправки форми застосування ПРРО буде увімкнено для відповідної конфігурації.Додайте ЕЦП для підписання фіскальних чеків відповідного субʼєку господарювання.
- В розділі ПРРО оберіть вкладку ЕЦП.
- Оберіть опцію “Додати ЕЦП”.
- Введіть бажану назву ЕЦП та субʼєкт господарювання, якому він належить.
- Завантажте файл ключа та введіть пароль до нього.
- Підтвердіть завантаження, натиснувши кнопку “Надіслати”.
Після цього наступні фіскальні чеки відповідного субʼєкта господарювання будуть підписуватися завантаженим ключем до його заміни чи видалення, або до моменту спливу терміну дії.
Якщо ви не користуєтеся мерчант-порталом, то для підключення ПРРО напишіть своєму аканут-менеджеру або команді підтримки на [email protected]
Отримання фіскальних чеків
Робота з фіскальними чеками можлива у такі способи:
- Відправка фіскальних чеків платнику.
- Отримання URL-посилання на фіскальний за запитом до API.
Відправка фіскальних чеків платнику
Відправка фіскальних чеків платнику здійснюється через ПРРО-провайдера у один із таких способів:
- За електронною поштою (за замовчуванням).
- За допомогою SMS.
- У Viber-повідомленні.
Відправка із використанням SMS чи Viber є платною і тарифікується згідно умов ПРРО-провайдера CashDesk: https://cashdesk.ua/prices
Для того, щоб встановити один із зазначених способів відправки фіскального чеку платнику, у запиті на Оплату (purchase), Зарахування резерву (capture), Повернення коштів (refund) додатково має передаватися параметр:
Parameter | Type | Required | Description |
---|---|---|---|
f_receipt_delivery | String | Fiscal receipt delivery option |
Для відправки через Email:
- Значення:
email
. - Платіжний запит повинен включати е-пошту платника (
customer_email
). Якщоcustomer_email
не передано, то відправка фіскального чека платнику не здійснюється.
Для відправки через SMS:
- Значення:
sms
. - Платіжний запит повинен включати номер телефону платника (
customer_phone
). Якщоcustomer_phone
не передано, то відправка фіскального чека платнику здійснюється за допомогою е-пошти, якщо її було передано.
Для відправки через Viber:
- Значення:
viber
. - Платіжний запит повинен супроводжуватися інформацією про номер телефону платника (
customer_phone
). Якщоcustomer_phone
не передано, то відправка фіскального чека платнику здійснюється за допомогою е-пошти, якщо її було передано.
Якщо в параметрі f_receipt_delivery
передати значення none
, то відправка фіскального чека платнику не здійснюється.
Якщо параметр f_receipt_delivery
не передається у запиті або передається з нестандартним значенням, то за замовчуванням відправка здійснюється за допомогою електронної пошти.
Отримання URL-посилання на фіскальний за запитом до API
URL-посилання на фіскальний чек також можна отримати у відповіді на запит про переопит статусу фіналізованої транзакції.
Між моментом обробки транзакції на стороні Tranzzo та моментом проведення фіскалізації на стороні податкових органів є затримка в часі, тому ми рекомендуємо відправляти запит на переопит статусу фіналізованої транзакції для отримання посилання на фіскальний чек не раніше ніж через 30с після отримання callback про успіх.
У відповіді на запит, серед інших параметрів, ви отримаєте:
{
…
"fiscal_receipt_url": "https://url.com/2fga245-3f12-4c88-8e0b-a54231abcdf9a/pdf",
…
}