API FONDYВерсія 1.0

Схема роботи програмного РРО

1. Торговець реєструє ПРРО в ДПС через подання форми J/F1316603.
2. Торговець реєструє всіх касирів шляхом подання форми J/F1391802.
3. Торговець реєструється в особистому кабінеті FONDY. Ми його називаємо мерчант-портал. Тут же потрібно завантажити ключі ПРРО. Про те, як їх отримати, описано нижче.
4. З мерчант-порталу ключі завантажуються в модуль ПРРО, в якому автоматично активується онлайн-каса FONDY.
5. Модуль програмного РРО, своєю чергою, отримує від ДПС реєстраційні дані касира, ПРРО та об’єкта оподаткування і зберігає їх для подальшої фіскалізації покупок.
6. У процесі покупки покупець переходить на сторінку з товаром або послугою інтернет-торговця.
7. Сайт інтернет-магазину формує класичний кошик для покупця (якщо кошика немає, то достатньо опису товару або послуги за умови, що це одна номенклатура).
8. Інформація про кошик/товар/послугу потрапляє на платіжний шлюз FONDY. Це може бути зроблено через:
   – один із понад 60 готових платіжних модулів для CMS і конструкторів сайтів (таких як Weblium, Wix, WooCommerce, Magento і т.д.);
   – виставлення онлайн-інвойсу за допомогою мерчант-порталу FONDY;
   – платіжну кнопку або посилання, які можна створити в мерчант-порталі;
   – пряму інтеграцію с API FONDY – для простоти можна скористатися готовими SDK для вашої мови розробки або мобільного додатка.
9. FONDY формує посилання на платіжну сторінку, на яку інтернет-магазин перенаправляє покупця для введення платіжних даних банківської картки.
10. Платіжний шлюз FONDY списує з картки покупця кошти.
11. Модуль ПРРО фіскалізує на сервері ДПС чек купівлі, передаючи вміст кошика з описом товарів і послуг.
12. ПРРО надсилає чек покупцеві на email. Приклад чека можна подивитися тут.
13. Наприкінці дня ПРРО автоматично формує Z-звіт і закриває зміну.
14. Надалі торговець може отримати всі звіти, які підтверджують фіскалізацію і необхідні для бухгалтерії, через мерчант-портал або API.

Фіскалізація покупки

Параметри, які необхідно передавати додатково для інтеграції з протоколом програмного РРО

У запит на купівлю додається параметр reservation_data – це JSON, закодований алгоритмом BASE64, який має таку структуру:

{
 "products": [
   {
     "id": 1,
     "name": "Мигдаль жар.",
     "price": 700.00,
     "total_amount": 140.00,
     "quantity": 0.2
   },
   {
     "id": 2,
     "name": "Кешью очищ.",
     "price": 850.00,
     "total_amount": 127.5,
     "quantity": 0.15
   }
 ]
}

Примітка

Якщо параметр reservation_data не передається, то чек буде сформовано з 1 одиниці товару з вартістю, зазначеною в параметрі amount та описом, зазначеним у order_desc

Параметри запиту

Фіскалізація розщеплення

У запит на разщеплення на https://pay.fondy.eu/api/settlement додається параметр reservation_data – це JSON, закодований алгоритмом BASE64, який має таку структуру:

{
 "products": [
   {
     "id": 1,
     "name": "Мигдаль жар.",
     "price": 700.00,
     "total_amount": 140.00,
     "quantity": 0.2
   },
   {
     "id": 2,
     "name": "Кешью очищ.",
     "price": 850.00,
     "total_amount": 127.5,
     "quantity": 0.15
   }
 ]
}

Примітка

Якщо параметр reservation_data не передається, то фіскалізація відбуватися не буде.

Приклад структури order в запиті на розщеплення

{
  "order": {
    "server_callback_url": "https://site.com/callback",
    "currency": "UAH",
    "amount": 10000,
    "order_type": "settlement",
    "order_id": "test642819XXXXXX2111_split1",
    "operation_id": "test642819XXXXXX2111",
    "order_desc": "test order",
    "merchant_id": 1396424,
    "receiver": [
      {
        "requisites": {
          "amount": 600000,
          "settlement_description": "Призначення платежу",
          "merchant_id": 500001,
          "reservation_data": "ewogInByb2R1Y3RzIjogWwogICB7CiAgICAgImlkIjogMSwKICAgICAibmFtZSI6ICLQodCy0LjQvdC90ZYg0LrRgNC40LvQuNGI0LrQuCIsCiAgICAgInByaWNlIjogMTAwMC4wMCwKICAgICAidG90YWxfYW1vdW50IjogNjAwMC4wMCwKICAgICAicXVhbnRpdHkiOiA2CiAgIH0KIF0KfQ=="
        },
        "type": "merchant"
      },
      {
        "requisites": {
          "amount": 400000,
          "settlement_description": "Призначення платежу",
          "merchant_id": 600001,
          "reservation_data": "ewogInByb2R1Y3RzIjogWwogICB7CiAgICAgImlkIjogMSwKICAgICAibmFtZSI6ICLQodCy0LjQvdC90ZYg0LrRgNC40LvQuNGI0LrQuCIsCiAgICAgInByaWNlIjogMTAwMC4wMCwKICAgICAidG90YWxfYW1vdW50IjogNDAwMC4wMCwKICAgICAicXVhbnRpdHkiOiA0CiAgIH0KIF0KfQo="
        },
        "type": "merchant"
      }
    ]
  }
}

В результаті розщеплення, на кожного мерчанта-отримувача, у якого налаштовано онлайн-касу в Мерчант-порталі, буде сформовано окремий фіскальний чек зі списком його товарів. При цьому, платник отримає окремий лист по кожному фіскальному чеку, якщо його email був вказаний при покупці.

Опитування деталей фіскального запису

Запит необхідно надсилати на https://pay.fondy.eu/api/get_kkt_logs методом POST

Приклад запиту (JSON)

{
  "request": {
    "order_id": "13731336126512",
    "merchant_id": 1396424,
    "signature": "2e4a8881c428037fdf266b18a29a282aba79ed58"
  }
}

Параметри запиту

Формат відповіді.

Приклад відповіді :

{
  "response": {
    "1499968937": {
      "request": {
        "CHECKPAY": [
          {
            "SUM": "80.00",
            "PAYSYS": [
              {
                "NAME": "ПЛАТІЖНА СИСТЕМА MasterCard",
                "AUTHCD": "46049Z",
                "EPZDETAILS": "444444XXXXXX1111",
                "ACQUIRETRANSID": "024046466130"
              }
            ],
            "PAYFORMCD": 1,
            "PAYFORMNM": "Електронним платіжним засобом"
          }
        ],
        "CHECKBODY": [
          {
            "CODE": 476657827,
            "COST": "80.00",
            "NAME": "Заказ №",
            "PRICE": "80.00",
            "VALCD": "980",
            "VALNM": "грн.",
            "AMOUNT": 1,
            "UNITNM": "од.",
            "VALSYMCD": "UAH",
            "DESCRIPTION": "desc"
          }
        ],
        "CHECKHEAD": {
          "TIN": "3263608852",
          "UID": "0E9B042D-888D-452C-B36B-12F283B76B02",
          "VER": 1,
          "ORGNM": "ТЕСТОВИЙ ПЛАТНИК",
          "CASHIER": "Тестовий платник",
          "DOCTYPE": 0,
          "LOGOURL": "https://logo.io/uploads/2021/logo.png",
          "OFFLINE": "false",
          "POINTNM": "ФОП Тестовий",
          "ORDERNUM": 4765,
          "ORDERDATE": "28122021",
          "ORDERTIME": "103735",
          "POINTADDR": "УКРАЇНА, ТЕРНОПIЛЬСЬКА ОБЛ., М. ТЕРНОПІЛЬ, м.Тернопіль, вул.Корольова,7/185",
          "DOCSUBTYPE": 0,
          "CASHDESKNUM": 1,
          "CASHREGISTERNUM": 4000000000
        },
        "CHECKTOTAL": {
          "SUM": 80,
          "RNDSUM": "0.00",
          "NORNDSUM": 80,
          "NOTAXSUM": 80
        }
      },
      "response": {
        "UID": "0E9B042D-888D-452C-B36B-12F283B76B02",
        "VER": "1",
        "ORDERNUM": "4765",
        "ERRORCODE": "0",
        "ORDERDATE": "28122021",
        "ORDERTIME": "103717",
        "ORDERTAXNUM": "123456789"
      },
      "type": "purchase"
    },
    "response_status": "success"
  }
}

Отримання графічної версії фіскального чека купівлі

Запит необхідно надсилати на https://pay.fondy.eu/kkt/ereceipt/check методом POST

Приклад запиту (JSON)

{
  "request": {
    "transaction_id": "1499968937",
    "merchant_id": 1396424,
    "receipt_type": "receipt",
    "signature": "2e4a8881c428037fdf266b18a29a282aba79ed58"
  }
}

Параметри запиту

"tran_type": "purchase" або "reverse" або "capture"

"receipt" або "zreport"

Приклад відповіді:

{
  "check_url": "https://merchportal-ereceipt.s3.amazonaws.com/ereceipt/check_1499968937.pdf?AWSAccessKeyId=YYYYYYYYYYYYYYYYYYYYYY&Signature=XXXXXXXXXXXXXXXXXXXXXXXX%3D&Expires=1956257837"
}