API FONDYВерсія 1.0

Розщеплення платежів (лише Україна)

  1. Тестові реквізити
  2. Методи розщеплення
  3. Покрокова інструкція інтеграції API
  4. Формат запиту
  5. Формат проміжного відповіді
  6. Формат фінальної відповіді
  7. Розрахунок підпису
  8. Повернення коштів
  9. Отримання статусу розщеплення
  10. Обробка колбеку
  11. Інтеграційні тести
  12. Перегляд звітів про розщеплення в Мерчант Порталі
  13. Фіскалізація

Тестові реквізити

ID мерчантаКлюч платежуОпис
1396424testОсновний (технічний) мерчант. Від імені цього мерчанта будуватиметься запит на API розщеплення і формуватиметься сигнатура
500001Мерчант контрагента 1, на якого необхідно розщепити першу частину суми
600001Мерчант контрагента 2, на якого необхідно розщепити другу частину суми

 

Методи розщеплення

АПІ розрахункового центру дає змогу розщеплювати платіж, оплачений платником, на кілька одержувачів – контрагентів.

У прикладі показано роботу з двома контрагентами, але їх може бути більше.

Реквізити всіх контрагентів передаються в запиті в параметрі receiver і можуть бути будь-якою з таких сутностей: 

Вільні реквізити рахунку IBAN

приклад:

"receiver":{
       "requisites": {
         "amount": 100,
         "settlement_description": "Призначення платежу для банківського переказу",
         "account": 123456789,
         "okpo": 1234567,
         "jur_name": "ТОВ Ромашка",
         "fee_partner_amount": 102
       },
       "type": "bank_account"
     }

Реквізити мерчанта

приклад:

"receiver":{
       "requisites": {
         "amount": 200,
         "settlement_description": "Призначення платежу для банківського переказу",
         "merchant_id": 600001,
         "fee_partner_amount": 102
       },
       "type": "merchant"
     }

Токен карти

приклад:

"receiver":{
       "requisites": {
         "rectoken": "da82035bc13c78f2eb74df7caf81decc3601061c",
         "amount": 500,
         "fee_partner_amount": 102
       },
       "type": "rectoken"
     }

Номер карти

приклад:

"receiver":{
       "requisites": {
         "amount": 500,
         "card_number": 4444555511116666,
         "fee_partner_amount": 102
       },
       "type": "card"
     }

Покрокова інструкція

Крок 1. Купівля

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

При цьому, платежу присвоюється унікальний order_id.

Якщо суму потрібно тільки заблокувати, але не списувати з картки, під час здійснення покупки, потрібно передати параметр preauth = Y

Сума, заблокована з параметром preauth = Y надалі може бути змінена в менший бік за допомогою операції capture.

Платіж, здійснений з параметром preauth = Y не списується з картки і не зараховується на рахунок Fondy до отримання запиту на операцію capture.

Платіж, здійснений з параметром preauth = N або без параметра preauth, списується з картки і зараховується на рахунок Fondy в очікуванні інструкції на розщеплення.

Крок 2. Capture (не обов’язковий)

Якщо на кроці 1 платіж було здійснено з параметром preauth = Y, його необхідно завершити операцією capture.

Крок 3. Розщеплення

Надіслати запит розщеплення на https://pay.fondy.eu/api/settlement передаючи параметр operation_id ідентичний order_id з кроку 1 та інструкцію розщеплення в параметрі receiver.

Формат запиту

Запит надсилається методом POST у форматі JSON на endpoint:

https://pay.fondy.eu/api/settlement

Формат запиту

{
 "request": {
   "version": 2.0,
   "data": "ewogIm9yZGVyIjogewogICAic2VydmVyX2NhbGxiYWNrX3VybCI6ICJodHRwOi8vc2l0ZS5jb20vY2FsbGJhY2siLAogICAicmVjdG9rZW4iOiAiOTg5YmI5MzRiZTZiMWEwYjRmZDc1YzU5YWRhZTczOTRlNTZmNGM2MCIsIC8vINC00LvRjyDQodGF0LXQvNCwIDIuINCf0L7RgdGA0LXQtNGB0YLQstC+0Lwg0YLQvtC60LXQvdCwCiAgICJjdXJyZW5jeSI6ICJVQUgiLAogICAiYW1vdW50IjogIjE0MDAiLAogICAib3JkZXJfdHlwZSI6ICJzZXR0bGVtZW50IiwKICAgInJlc3BvbnNlX3VybCI6ICJodHRwOi8vc2l0ZS5jb20vdGVzdC9yZXNwb25zZXBhZ2UvIiwKICAgIm9yZGVyX2lkIjogInRlc3QxMjM0NTYxNDY3NDYyMDk5LjE5IiwKICAgIm9wZXJhdGlvbl9pZCI6ICJ0ZXN0MTIzNDU2MTQ2NzQ2MjA5OS4xOSIsCiAgICJvcmRlcl9kZXNjIjogInRlc3Qgb3JkZXIiLAogICAibWVyY2hhbnRfaWQiOiAxMzk2NDI0LAogICAicmVjZWl2ZXIiOiBbCiAgICAgewogICAgICAgInJlcXVpc2l0ZXMiOiB7CiAgICAgICAgICJhbW91bnQiOiAxMDAsCiAgICAgICAgICJzZXR0bGVtZW50X2Rlc2NyaXB0aW9uIjogItCd0LDQt9C90LDRh9C10L3QuNC1INC/0LvQsNGC0LXQttCwINC00LvRjyDQsdCw0L3QutC+0LLRgdC60L7Qs9C+INC/0LXRgNC10LLQvtC00LAiLAogICAgICAgICAibWVyY2hhbnRfaWQiOiA1MDAwMDEKICAgICAgIH0sCiAgICAgICAidHlwZSI6ICJtZXJjaGFudCIKICAgICB9LHsKICAgICAgICJyZXF1aXNpdGVzIjogewogICAgICAgICAiYW1vdW50IjogMjAwLAogICAgICAgICAic2V0dGxlbWVudF9kZXNjcmlwdGlvbiI6ICLQndCw0LfQvdCw0YfQtdC90LjQtSDQv9C70LDRgtC10LbQsCDQtNC70Y8g0LHQsNC90LrQvtCy0YHQutC+0LPQviDQv9C10YDQtdCy0L7QtNCwIiwKICAgICAgICAgIm1lcmNoYW50X2lkIjogNjAwMDAxCiAgICAgICB9LAogICAgICAgInR5cGUiOiAibWVyY2hhbnQiCiAgICAgfSwKICAgICB7CiAgICAgICAicmVxdWlzaXRlcyI6IHsKICAgICAgICAgImFtb3VudCI6IDEwMCwKICAgICAgICAgInNldHRsZW1lbnRfZGVzY3JpcHRpb24iOiAi0J3QsNC30L3QsNGH0LXQvdC40LUg0L/Qu9Cw0YLQtdC20LAg0LTQu9GPINCx0LDQvdC60L7QstGB0LrQvtCz0L4g0L/QtdGA0LXQstC+0LTQsCIsCiAgICAgICAgICJhY2NvdW50IjogMTIzNDU2Nzg5LAogICAgICAgICAibWZvIjogMTIzNDUsCiAgICAgICAgICJva3BvIjogMTIzNDU2Nzg5LAogICAgICAgICAianVyX25hbWUiOiAi0J7QntCeINCg0L7QvNCw0YjQutCwIgogICAgICAgfSwKICAgICAgICJ0eXBlIjogImJhbmtfYWNjb3VudCIKICAgICB9LAogICAgIHsKICAgICAgICJyZXF1aXNpdGVzIjogewogICAgICAgICAicmVjdG9rZW4iOiAiZGE4MjAzNWJjMTNjNzhmMmViNzRkZjdjYWY4MWRlY2MzNjAxMDYxYyIsCiAgICAgICAgICJhbW91bnQiOiA1MDAKICAgICAgIH0sCiAgICAgICAidHlwZSI6ICJyZWN0b2tlbiIKICAgICB9LAogICAgIHsKICAgICAgICJyZXF1aXNpdGVzIjogewogICAgICAgICAiYW1vdW50IjogNTAwLAogICAgICAgICAiY2FyZF9udW1iZXIiOiA0NDQ0NTU1NTExMTE2NjY2CiAgICAgICB9LAogICAgICAgInR5cGUiOiAiY2FyZCIKICAgICB9CiAgIF0KIH0KfQo=",
   "signature": "943571471619207087eb57e2b4ef69affd337b1a"
 }
}

data – це base64 кодований набір даних формату:

{
 "order": {
   "server_callback_url": "http://site.com/callback",
   "currency": "UAH",
   "amount": 1400,
   "order_type": "settlement",
   "response_url": "http://site.com/test/responsepage/",
   "order_id": "settlement_test1234561467462099.19",
   "operation_id": "test1234561467462099.19",
   "order_desc": "test order",
   "merchant_id": 1396424,
   "receiver": [
     {
       "requisites": {
         "amount": 100,
         "settlement_description": "Призначення платежу для банківського переказу",
         "merchant_id": 500001,
         "fee_partner_amount": 102
       },
       "type": "merchant"
     },{
       "requisites": {
         "amount": 200,
         "settlement_description": "Призначення платежу для банківського переказу",
         "merchant_id": 600001,
         "fee_partner_amount": 90
       },
       "type": "merchant"
     },
     {
       "requisites": {
         "amount": 100,
         "settlement_description": "Призначення платежу для банківського переказу",
         "account": 123456789,
         "okpo": 1234567,
         "jur_name": "ТОВ Ромашка",
         "fee_partner_amount": 70
       },
       "type": "bank_account"
     },
     {
       "requisites": {
         "rectoken": "da82035bc13c78f2eb74df7caf81decc3601061c",
         "amount": 500,
         "fee_partner_amount": 50
       },
       "type": "rectoken"
     },
     {
       "requisites": {
         "amount": 500,
         "card_number": 4444555511116666,
         "fee_partner_amount": 40
       },
       "type": "card"
     }
   ]
 }
}

Формат кінцевої відповіді

Відповідь повертається у форматі JSON на server_callback_url та response_url після того, як клієнт завершить оплату

Формат кінцевої відповіді:

{
 "response": {
   "version": "2.0",
   "data": "ewogICJvcmRlciI6IHsKICAgICJycm4iOiAiIiwKICAgICJtYXNrZWRfY2FyZCI6ICI0NDQ0NTVYWFhYWFg2NjY2IiwKICAgICJzZW5kZXJfY2VsbF9waG9uZSI6ICIiLAogICAgInJlc3BvbnNlX3N0YXR1cyI6ICJzdWNjZXNzIiwKICAgICJzZW5kZXJfYWNjb3VudCI6ICIiLAogICAgImZlZSI6ICIiLAogICAgInJlY3Rva2VuX2xpZmV0aW1lIjogIiIsCiAgICAicmV2ZXJzYWxfYW1vdW50IjogIjAiLAogICAgInNldHRsZW1lbnRfYW1vdW50IjogIjAiLAogICAgImFjdHVhbF9hbW91bnQiOiAiMjAwMCIsCiAgICAib3JkZXJfc3RhdHVzIjogImFwcHJvdmVkIiwKICAgICJyZXNwb25zZV9kZXNjcmlwdGlvbiI6ICIiLAogICAgInZlcmlmaWNhdGlvbl9zdGF0dXMiOiAiIiwKICAgICJvcmRlcl90aW1lIjogIjAyLjA3LjIwMTYgMTU6MjE6MzkiLAogICAgImFjdHVhbF9jdXJyZW5jeSI6ICJVQUgiLAogICAgIm9yZGVyX2lkIjogInRlc3QxMjM0NTYxNDY3NDYyMDk5LjE5IiwKICAgICJwYXJlbnRfb3JkZXJfaWQiOiAiIiwKICAgICJtZXJjaGFudF9kYXRhIjogIiIsCiAgICAidHJhbl90eXBlIjogInB1cmNoYXNlIiwKICAgICJlY2kiOiAiIiwKICAgICJzZXR0bGVtZW50X2RhdGUiOiAiIiwKICAgICJwYXltZW50X3N5c3RlbSI6ICJjYXJkIiwKICAgICJyZWN0b2tlbiI6ICIiLAogICAgImFwcHJvdmFsX2NvZGUiOiAiNDc4NDUwIiwKICAgICJtZXJjaGFudF9pZCI6IDEzOTY0MjQsCiAgICAic2V0dGxlbWVudF9jdXJyZW5jeSI6ICIiLAogICAgInBheW1lbnRfaWQiOiAxNTg2MTkzLAogICAgInRyYW5zYWN0aW9uIjogWwogICAgICB7CiAgICAgICAgInN0YXR1cyI6ICJhcHByb3ZlZCIsCiAgICAgICAgImFtb3VudCI6IDIwLjAsCiAgICAgICAgImZlZSI6IDAuMCwKICAgICAgICAicmV2ZXJzYWxfYW1vdW50IjogMC4wLAogICAgICAgICJwYXJlbnRfdHJhbl9pZCI6IG51bGwsCiAgICAgICAgInJlY2VpdmVyIjoge30sCiAgICAgICAgIm1lcmNoYW50X2lkIjogNjAwMDAxLAogICAgICAgICJ0eXBlIjogInB1cmNoYXNlIiwKICAgICAgICAiaWQiOiAxMDAxNTQzOTYwLAogICAgICAgICJkb2Nfbm8iOiBudWxsCiAgICAgIH0KICAgIF0sCiAgICAicHJvZHVjdF9pZCI6ICIiLAogICAgImN1cnJlbmN5IjogIlVBSCIsCiAgICAiY2FyZF9iaW4iOiA0NDQ0NTUsCiAgICAicmVzcG9uc2VfY29kZSI6ICIiLAogICAgImNhcmRfdHlwZSI6ICJWSVNBIiwKICAgICJhbW91bnQiOiAiMjAwMCIsCiAgICAic2VuZGVyX2VtYWlsIjogImRlbW9AZm9uZHkuZXUiCiAgfQp9",
   "signature": "54aeeadf05b04e2e4097a4aa5907c3a62684d058"
 }
}

де data – це base64 кодований набір даних, що містять інформацію про всі фінансові операції та їхній статус

{
 "order": {
   "rrn": "",
   "masked_card": "444455XXXXXX6666",
   "sender_cell_phone": "",
   "response_status": "success",
   "sender_account": "",
   "fee": "",
   "rectoken_lifetime": "",
   "reversal_amount": "0",
   "settlement_amount": "0",
   "actual_amount": "2000",
   "order_status": "approved",
   "response_description": "",
   "verification_status": "",
   "order_time": "02.07.2016 15:21:39",
   "actual_currency": "UAH",
   "order_id": "test1234561467462099.19",
   "parent_order_id": "",
   "merchant_data": "",
   "tran_type": "purchase",
   "eci": "",
   "settlement_date": "",
   "payment_system": "card",
   "rectoken": "",
   "approval_code": "478450",
   "merchant_id": 1396424,
   "settlement_currency": "",
   "payment_id": 1586193,
   "transaction": [
     {
       "status": "approved",
       "amount": 20.0,
       "fee": 0.0,
       "reversal_amount": 0.0,
       "parent_tran_id": null,
       "receiver": {},
       "merchant_id": 600001,
       "type": "purchase",
       "id": 1001543960,
       "doc_no": null
     }
   ],
   "product_id": "",
   "currency": "UAH",
   "card_bin": 444455,
   "response_code": "",
   "card_type": "VISA",
   "amount": "2000",
   "sender_email": "demo@fondy.eu"
 }
}

Розрахунок сигнатури

Параметр signature розраховується як функція sha1(password + ‘|’ +data)

Повернення коштів

При поверненні коштів, в параметрах receiver->requisites-> потрібно вказувати, з якого мерчанта яка частина основної суми має бути утримана.

Наприклад, якщо основна сума “amount”: 300, то потрібно в запиті вказати receiver->receiver->amount таким чином, щоб усі їхні значення разом дорівнювали основній сумі.

Основна сума повернеться на картку платника або в режимі онлайн, або за регламентом банку протягом декількох днів, якщо онлайн реверс неможливий.

POST: https://pay.fondy.eu/api/reverse/order_id

Приклад параметра data:

{
  "order": {
    "order_id": "test1234561467462099.19",
    "currency": "UAH",
    "amount": 300,
    "merchant_id": 1396424,
    "receiver": [
      {
        "requisites": {
          "amount": 100,
          "merchant_id": 500001
        },
        "type": "merchant"
      },
      {
        "requisites": {
          "amount": 200,
          "merchant_id": 600001
        },
        "type": "merchant"
      }
    ]
  }
}

де: order_id і merchant_id – ідентифікатори оригінального платежу Приклад відповіді в разі успішного повернення:

{
  "order": {
    "reverse_status": "approved",
    "reversal_amount": "300",
    "order_id": "test1234561467462099.19",
    "response_status": "success",
    "response_code": "",
    "response_description": "",
    "merchant_id": 1396424
  }
}

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

{
  "order": {
    "reverse_status": "declined",
    "reversal_amount": "300",
    "order_id": "test1234561467462099.19",
    "response_status": "success",
    "response_code": "1016",
    "response_description": "Merchant not found",
    "merchant_id": 1396424
  }
}

Отримання статусу розщеплення

При створенні на боці FONDY платіжної інструкції на розщеплення, процес обробки інструкції проходить у три статуси: created -> processing -> approved

created: інструкція отримана та поставлена в чергу на розщеплення

approved: система СЕП НБУ підтвердила, що кошти зараховані отримувачам

Для отримання статусу розщеплення, потрібно використовувати API Отримання списку транзакцій. В параметрах order_id та merchant_id потрібно передавати значення того ордера, який містив інструкцію розщеплення в параметрі receiver.

При успішному розщепленні у списку транзакцій будуть транзакції з tran_type=settlement та transaction_status=approved які відповідають розщепленим сумам.

Розщеплення проходить за регламентом у термін, вказаний у договорі між мерчантом та FONDY.

 

Обробка колбека

Після отримання запиту на розщеплення, на server_callback_url, вказаний при покупці, буде повернений колбек у форматі

{
  "version": "2.0",
  "data": "eyJvcmRl...tZW50X2N1cnJlbmN5IjogIiJ9fQ==",
  "signature": "21fdf2e7938a7c6b7b883b4d7698e55e781b2445"
}

де параметр data містить структуру:

{
  "order": {
    "payment_id": 248671633,
    "fee": "",
    "order_type": "settlement",
    "reversal_amount": "0",
    "order_id": "1299382-settlement-test1595856030",
    "settlement_amount": "0",
    "merchant_data": "",
    "settlement_date": "",
    "transaction": [
      {
        "status": "approved",
        "odb_ref": null,
        "doc_no": null,
        "currency": "UAH",
        "settlement_response_code": "",
        "merchant_id": 700001,
        "id": 1241093791,
        "settlement_currency": "UAH",
        "settlement_fee": 0.01,
        "fee": 1,
        "reversal_amount": 0,
        "settlement_amount": 0.25,
        "settlement_status": "created",
        "amount": 25,
        "settlement_response_description": "",
        "parent_tran_id": null,
        "receiver": {
          "requisites": {
            "merchant_id": 500001
          },
          "type": "merchant"
        },
        "payouttime": "28.07.2020 08:00:00",
        "type": "settlement"
      },
      {
        "status": "approved",
        "odb_ref": null,
        "doc_no": null,
        "currency": "UAH",
        "settlement_response_code": "",
        "merchant_id": 700001,
        "id": 1241093793,
        "settlement_currency": "UAH",
        "settlement_fee": 10.38,
        "fee": 1038,
        "reversal_amount": 0,
        "settlement_amount": 374.0,
        "settlement_status": "created",
        "amount": 37400,
        "settlement_response_description": "",
        "parent_tran_id": null,
        "receiver": {
          "requisites": {
            "merchant_id": 600001
          },
          "type": "merchant"
        },
        "payouttime": "28.07.2020 08:00:00",
        "type": "settlement"
      }
    ],
    "operation_id": "1299382-test",
    "order_status": "approved",
    "response_description": "",
    "merchant_id": 1396424,
    "order_time": "27.07.2020 16:20:30",
    "response_code": "",
    "settlement_currency": ""
  }
}

У колбеці за таким запитом буде повернений об’єкт order, який містить тип замовлення order_type = settlement.

Параметр order_status вказує на те, чи оброблено запит на розщеплення, чи відхилено.

order_status об’єкта order може приймати 2 значення:

approved – запит на розщеплення оброблено

declined – запит на розщеплення відхилено

Причина та опис відмови при статусі declined повертається в параметрах response_code та response_description.

Об’єкт order також складається з масиву об’єктів transaction, який містить список транзакцій, на які розщепилась покупка. У кожній такій транзакції вказано type = settlement.

Параметр status об’єкта transaction може приймати такі значення:

created – транзакція розщеплення ще не оброблена

approved – транзакція розщеплення успішно оброблена, і кошти надійдуть на рахунок отримувача

Інтеграційні тести

Перед запуском у робочому режимі, потрібно переконатися, що інтеграція проведена відповідно до документації.

Для цього потрібно виконати ряд тестових операцій та надати ідентифікатори order_id команді технічної підтримки Fondy.

Тестові операції повинні бути виконані за реальною картою на невелику суму, зазвичай у межах 1-2 грн.

Тести:

  1. Покупка
  2. Покупка з preauth = Y та capture на повну суму – обов’язково, якщо використовується двоступінчаста модель блокування коштів та списання
  3. Покупка з preauth = Y та capture на часткову суму – обов’язково, якщо використовується двоступінчаста модель блокування коштів та списання
  4. Розщеплення на суму покупки з тесту 1
  5. Розщеплення на суму повного capture з тесту 2 – обов’язково, якщо використовується preauth = Y 
  6. Розщеплення на суму часткового capture з тесту 3 – обов’язково, якщо використовується preauth = Y 
  7. Розщеплення на некоректну суму (отримання status = declined)
  8. Повторне розщеплення вже розщепленого order_id (отримання status = declined)
  9. Обробка колбеку по успішному розщепленню з тесту 4 (статус HTTP 200 OK на server_callback_url)
  10. Обробка колбеку по не успішному розщепленню з тесту 7 (статус HTTP 200 OK на server_callback_url)

Перегляд звітів про розщеплення в Мерчант Порталі

Для моніторингу платежів та фінансових звітів використовуйте звіти в особистому кабінеті Мерчант-портала. Для цього увійдіть до Мерчант-портал і перейдіть в меню Звіти -> Користувацькі звіти. У цьому меню вам будуть доступні два основних звіти:

  • Нерозщеплені платежі – список всіх, не розщеплених з різних причин платежів.
  • Розщеплення – список всіх розщеплених платежів, та інформацію про отримувачів і статусах отримання коштів.

Нерозщеплені платежі

Як правило, основними причинами, через які платежі не розщеплюються, є:

  • відсутність запиту на розщеплення. Коли покупка платником здійснена, але запиту на https://pay.fondy.eu/api/settlement не було відправлено
  • запит на розщеплення прийшов з некоректною сумою. Це або сума всіх розщеплень на отримувачів не дорівнює сумі покупки, або не дорівнює сумі capture
  • в запиті на розщеплення в параметрі receiver вказаний merchant_id, який ще не активований з боку Fondy

Розщеплення

Звіт по розщепленням відображає детальну інформацію про те, куди надійшли кошти, в якому обсязі, в які дати.

Цей звіт можна використовувати як в ручному режимі, так і для автоматизованих фінансових підборів через API звітів. Для цього в звіті потрібно використовувати report_id = 595

Фіскалізація

Дивіться розділ API для програмного РРО -> Фіскалізація розщеплення

Хочу приймати платежі з усього світу!