Підключення програмного РРО

Як налаштувати роботу ПРРО

Зареєструйте касу в нашого партнера-провайдера ПРРО

Доступні провайдери ПРРО:
- Cash Desk
- Checkbox
Внесіть нові параметри в 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.f_receipt_delivery = “email”`
`customer_phone`	String		Мобільний номер платника. Обовʼязковий, якщо `products.f_receipt_delivery = “viber” або “sms”`
`products.taxes.type`	String		Тип податку (допустимі значення vat, non-vat). Якщо субʼєкт господарювання не є платником ПДВ має передаватися значення `non-vat`
`products.taxes.prc`	Number		Податкова ставка % (допустимі значення 0, 7, 14, 20)
`products.f_receipt_delivery`	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": "424242******4242",
  "exp_month": 12,
  "exp_year": 24,
  "cc_cvv": "***",
  "order_id": "123456789",
  "description":"Опис товару",
  "payway": "cc",
  "order_3ds_bypass": "supported",
  "customer_email": "[email protected]",
  "customer_phone": "+38(066) 123-45-67",
  "f_receipt_delivery": "email",
  "products": [{
    "id": "1",
    "name": "product name",
    "unit": "pc",
    "bar_code":"4876534567183",
    "amount": 50,
    "taxes": [{"type":"vat", "prc": 20}],
    "qty": 2
  }],
  "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-запит, то платежі не будуть проходити через відсутність обов'язкових параметрів.

Підключіть ПРРО через мерчант-портал

Відкрийте загальні налаштування мерчантського облікового запису та оберіть пункт ПРРО.
Натисніть кнопку Нова конфігурація.
Заповніть форму:
- Імʼя конфігурації: будь-яке значення на ваш вибір.
- Надавач послуг: провайдер ПРРО, в якому ви зареєстрували касу (доступні до вибору CashDesk та Checkbox).
  - Кроки при виборі CashDesk:
    - Ідентифікатор каси (ПРРО ID):
      приклад даних із Cash Desk параметрів "num_fiscal": “100000000000”
    - API-токен із сервісу-провайдера ПРРО:
      приклад даних із Cash Desk “api_token” : "00000000-0000-0000-0000-000000000000
    - Область застосування: оберіть зі списку потрібну юридичну особу чи ФОП.
    - Переведіть в активне положення перемикач “Увімкнути використання ПРРО при проведення платежів”. Має виглядати як на скріншоті нижче.
  - Кроки при виборі Checkbox:
    - Ключ ліцензії (License Key) з порталу Checkbox, знайти можна у вкладці Каси → клік двічі на Касу → Ключ ліцензії
      приклад даних з каси Checkbox:
      Ключ ліцензії: teste9fc2df61270d29d87975dac
    - Пін-код(PinCode) - знайти можна у вкладці Касири → клік двічі на Касира → Пін-код
      приклад даних:
      Пін-код: 9577655887
Перевірте дані та відправте форму.
Після відправки форми застосування ПРРО буде увімкнено для відповідної конфігурації.
Додайте ЕЦП для підписання фіскальних чеків відповідного субʼєку господарювання.
- В розділі ПРРО оберіть вкладку ЕЦП.
- Оберіть опцію “Додати ЕЦП”.
- Введіть бажану назву ЕЦП та субʼєкт господарювання, якому він належить.
- Завантажте файл ключа та введіть пароль до нього.
- Підтвердіть завантаження, натиснувши кнопку “Надіслати”.

SBCR

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

інформація

Якщо ви не користуєтеся мерчант-порталом, то для підключення ПРРО напишіть своєму аканут-менеджеру або команді підтримки на [email protected]

Отримання фіскальних чеків

Робота з фіскальними чеками можлива у такі способи:

Відправка фіскальних чеків платнику.
Отримання URL-посилання на фіскальний за запитом до API.

Відправка фіскальних чеків платнику

Відправка фіскальних чеків платнику здійснюється через ПРРО-провайдера у один із таких способів:

За електронною поштою (за замовчуванням).
За допомогою SMS.
У Viber-повідомленні.

Важливо

Відправка із використанням SMS чи Viber є платною і тарифікується згідно умов ПРРО-провайдера:

CashDesk: https://cashdesk.ua/prices
Checkbox https://wiki.checkbox.ua/uk/portal/billing

Для того, щоб встановити один із зазначених способів відправки фіскального чеку платнику, у запиті на Оплату (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",
…
}

Як налаштувати роботу ПРРО​

Зареєструйте касу в нашого партнера-провайдера ПРРО​

Внесіть нові параметри в API-запит​

Підключіть ПРРО через мерчант-портал

Отримання фіскальних чеків​

Як налаштувати роботу ПРРО

Зареєструйте касу в нашого партнера-провайдера ПРРО

Внесіть нові параметри в API-запит

Отримання фіскальних чеків