API FONDYВерсія 1.0

API для запиту користувацьких звітів

Загальна інформація про API
Токен доступу
Отримання даних звіту
Використання фільтрів
Список доступних звітів

Загальна інформація про API

Всі запити відправляються через HTTPS методом POST.

Формат запиту та відповіді – JSON.

Структура JSON-відповіді завжди є словником (асоціативним масивом).

Якщо присутній ключ err_code або error, запит не виконано. У такому випадку параметри err_code та error у відповіді є описом помилки.

Основні коди помилок:
Необхідний токен авторизації – токен не передано в заголовку запиту
Недійсний токен авторизації – токен або недійсний, або застарілий
Мерчант не знайдений – мерчант не знайдений
У вас немає доступу до цього звіту – або report_id недійсний, або у вас немає доступу до звіту

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

{
   "error": "Необхідний токен авторизації",
   "err_code": "Необхідний токен авторизації"
}

Токен авторизації token повинен бути відправлений в заголовку Authorization вашого запиту. Приклад:

curl 'https://portal.fondy.eu/api/extend/company/report/' \
-H "Authorization: Token 4cDY6LgviVN85g70eDHXygrmYTourFAT"

Токен доступу

Надішліть POST-запит до кінцевої точки:

https://portal.fondy.eu/authorizer/token/application/get

передаючи дані у вигляді асоціативного масиву:

Параметр	Тип	Опис	Приклад
`application_id`	string(20)	ID компанії. Зверніться до підтримки FONDY для отримання ID та секретного ключа. обов’язковий	1234
`date`	string(1024)	Дата в будь-якому форматі. Дата є сіллю для підпису хеша sha512 обов’язковий	2020-04-06 11:15:27 або 1586171872 або будь-який інший рядок
`signature`	string(128)	Підпис обов’язковий	7eec02ed1088b47da639549a109c0e98a75e2d8c76dfa33db4ee18359b2ea677dda37516abc0e439b286261a48d49d3e2fd885d9f09c8ff5c7308afe4180688a

Підпис формується шляхом конкатенації приватного ключа компанії, ідентифікатора компанії та параметра дати через вертикальну риску | (в кодуванні utf-8). З отриманого рядка потрібно взяти хеш sha512 в hex.

Приклади отримання підпису.

Python 3.6:

from datetime import datetime
import hashlib

date = str(datetime.now())
company_id = str(%your_company_id%)
signature = hashlib.sha512('|'.join(['%your_company_private_key%', company_id, date]).encode('utf-8')).hexdigest()

PHP 7.2:

<?php
$date = strtotime("now");
$company_id = %application_id%;
$signature = hash('sha512', join('|',array('%your_company_private_key%', $company_id, $date)));

Приклад curl-запиту:

curl 'https://portal.fondy.eu/authorizer/token/application/get' \
    -H "Content-Type: application/json; charset=utf-8" \
    -X POST  --data-binary @- <<EOF
    {
        "signature": "5124cef4e69a015c1662f0ff963adc9f85ff60e365445ffcf6688737da726becb298211e5040c9ac74e3f56ff1065b42c281e300370436bec539f6b2679b91ee",
        "application_id": "2",
        "date": "2020-04-06 11:15:27"
    }
EOF

У разі успіху токен буде міститися в параметрі token відповіді JSON і закінчиться через 1 годину:

{
  "request_id": "SuVhZRMS7JDD2iGS",
  "token": "Yq0GXWeOZ1m8BsiCa4iQPDB84Wjw346",
  "expires_in": 3602
}

В іншому випадку відповідь буде містити ключі error_code та error_message.

{
  "error_code": 403,
  "error_message": "Incorrect signature",
  "request_id": "cGeC7PH59ESqQw30"
}

Отримати дані звіту

Надішліть POST-запит на кінцеву точку: https://portal.fondy.eu/api/extend/company/report/

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

Параметр	Тип	Опис	Приклад
`filters`	JSON objects[]	Набір фільтрів, індивідуальних для кожного звіту (report_id) обов’язковий	“filters”: [ { “s”: “settlement_date”, “m”: “dateis”, “v”: “2019-01-24” } ]
`merchant_id`	integer(12)	Унікальний ідентифікатор мерчанта. Генерується FONDY під час реєстрації мерчанта. обов’язковий	1396424
`report_id`	integer(12)	Повідомте унікальний ідентифікатор (див. Список доступних звітів) обов’язковий	500
`on_page`	integer(12)	Ліміт записів, які повертаються в контексті одного запиту (рекомендується від 10 до 500) обов’язковий	500
`page`	integer(12)	Записує зміщення сторінки. Наприклад, при on_page = 50, щоб отримати дані з 51 по 100, потрібно передати page = 2 обов’язковий	2

Параметри відповіді:

Параметр	Тип	Опис	Приклад
`data`	JSON objects[][]	Набір даних у вигляді відсортованого двовимірного масиву JSON	“data”: [ [ 1234567890, 10000000001 ], [ 1234567891, 10000000002 ] ]
`fields`	string[]	Список полів, що повертаються	“fields”: [ “payment_id”, “order_time”, “order_status”, “actual_amount”, “currency”, “fee”, “order_id”, “settlement_amount”, “settlement_currency”, “settlement_date”, “settlement_status”, “odb_ref”, “tran_time”, “settlement_type”, “payment_system”, “sender_email”, “order_desc”, “merchant_data”, “settlement_desc”, “transaction_id” ]
`rows_count`	integer(12)	Кількість записів у повному наборі даних	500
`rows_on_page`	integer(12)	Кількість записів, повернутих в контексті цього запиту	50
`rows_page`	integer(12)	Зсув діапазону в повному наборі даних. Наприклад, якщо rows_on_page = 50 і rows_page = 2, то в контексті цього запиту повертаються записи з 51 по 100	2

Приклад запиту:

curl 'https://portal.fondy.eu/api/extend/company/report/' \
-H "Authorization: Token k1y0qXZ6KgO4GIfkeRlEznao0zbzYdhf" \
-d @- << EOF
{
  "on_page": 10,
  "page": 1,
  "filters": [
    {
      "s": "settlement_date",
      "m": "from",
      "v": "2019-01-24"
    },
    {
      "s": "settlement_date",
      "m": "to",
      "v": "2019-01-27"
    },
    {
      "s": "actual_amount",
      "m": "=",
      "v": "630.00"
    }
  ],
  "merchant_id": 1398432,
  "report_id": "403"
}
EOF

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

{
  "data": [
    [
      1234567890,
      "2019-01-23 10:58:38",
      "approved",
      "630.00",
      "UAH",
      "11.97",
      "test-25697841-1",
      "618.03",
      "EUR",
      "2019-01-24 08:00:00",
      "completed",
      "2426012568",
      "2019-01-23 10:58:38",
      "purchase",
      "Visa/MC",
      "test@test.com",
      "Test order 1",
      "[]",
      "Test payment 1",
      10000000001
    ],
    [
      1234567891,
      "2019-01-23 10:56:51",
      "approved",
      "572.86",
      "UAH",
      "10.88",
      "test-94341241-1",
      "561.98",
      "EUR",
      "2019-01-24 08:00:00",
      "completed",
      "2426012568",
      "2019-01-23 10:56:51",
      "purchase",
      "Visa/MC",
      "test2@test.com",
      "Test order 2",
      "[]",
      "Test payment 2",
      10000000002
    ]
  ],
  "rows_count": 2,
  "fields": [
    "payment_id",
    "order_time",
    "order_status",
    "actual_amount",
    "currency",
    "fee",
    "order_id",
    "settlement_amount",
    "settlement_currency",
    "settlement_date",
    "settlement_status",
    "odb_ref",
    "tran_time",
    "settlement_type",
    "payment_system",
    "sender_email",
    "order_desc",
    "merchant_data",
    "settlement_desc",
    "transaction_id"
  ],
  "rows_page": 1,
  "rows_on_page": 10
}

Використовуйте фільтри

Фільтр – це масив JSON-об’єктів.

Кожен об’єкт фільтра повинен містити наступні атрибути:

s – назва поля, до якого застосовується фільтр
m – оператор пошуку (=, <, > тощо, залежно від типу поля )
v – значення поля для фільтрації

Приклад фільтра

[
    {
      "s": "settlement_date",
      "m": "dateis",
      "v": "2019-01-24"
    }
]

Операнди в залежності від типу поля:

float: ‘=’, ‘>’, ‘<‘, ‘!=’, ‘isnull’, ‘notnull’
int: ‘=’, ‘>’, ‘<‘, ‘!=’, ‘any’, ‘isnull’, ‘notnull’
date: ‘dateis’, ‘from’, ‘to’, ‘isnull’, ‘notnull’, ‘notdate’
text: ‘=’, ‘!=’, ‘like’, ‘!like’, ‘start’, ’empty’, ‘any’, ‘notnull’
bool: istrue
select: ‘=’, ‘!=’, ‘any’
array: in_array
daterange: ‘daterange’

Неочевидні режими пошуку:

будь-який:
{“s”: “id”, “m”: “=”, “v”: “10,20,30”} – фільтрування значень, вказаних через кому

фільтр застосовується як id у (10,20,30)

від:
{“s”: “timestart”, “m”: “from”, “v”: “2020-01-10”}

фільтр застосовується як timestart >= ‘2020-01-10’

{“s”: “timestart”, “m”: “from”, “v”: “-2”}

фільтр застосовується як timestart >= зараз() – 2 дні

до:
{“s”: “timestart”, “m”: “to”, “v”: “2020-01-10”}

фільтр застосовується як timestart < ‘2020-01-11‘

dateis – “день рівний” – дані фільтруються від початку вказаного дня (00:00) до початку наступного дня (00:00) (не включаючи наступний день)
like – фільтрує відповідно до часткового збігу фрагмента
!like – частковий фрагмент не повинен збігатися
start – “починаючи з”

Список доступних звітів

ID звіту	Поля	Обов’язкові поля для фільтрації	Приклад фільтра	Приклад
666	merchant_order_id - рядок(1000) payment_id - ціле(12) authorization_date - datetime(РРРР-ММ-ДД ГГ:ХХ:СС) operation_type - рядок(1000) odbref - рядок(1000) amount - десяткове(19,2) order_description - рядок(1000) currency - рядок(3) fee_currency - рядок(3) transaction_rate - десяткове(19,6) settlement_rate - десяткове(19,6) fee_rate - десяткове(19,6) gross - десяткове(19,2) commission - десяткове(19,2) batch_number - ціле(12) settlement_amount - десяткове(19,2) url - рядок(1000) settlement_date - datetime(РРРР-ММ-ДД ГГ:ХХ:СС) rolling_reserve_amount - десяткове(19,2) rolling_reserve_currency - рядок(3) rolling_reserve_settlement_date - datetime(РРРР-ММ-ДД ГГ:ХХ:СС) deposit_setllement_amount - десяткове(19,2) settlement_currency - рядок(3) merchant_data - рядок(1000)	settlement_date OR authorization_date OR payment_id	[ { "s": "settlement_date", "m": "dateis", "v": "2019-01-24" } ]	Звіт про розрахунки EU
403	payment_id - ціле(12) order_time - datetime(РРРР-ММ-ДД ГГ:ХХ:СС) order_status - рядок(1000) actual_amount - десяткове(19,2) currency - рядок(3) fee - десяткове(19,2) order_id - рядок(1000) settlement_amount - десяткове(19,2) settlement_currency - рядок(3) settlement_date - datetime(РРРР-ММ-ДД ГГ:ХХ:СС) settlement_status - рядок(1000) odb_ref - рядок(1000) tran_time - datetime(РРРР-ММ-ДД ГГ:ХХ:СС) settlement_type - рядок(1000) payment_system - рядок(1000) sender_email - рядок(1000) order_desc - рядок(1000) merchant_data - рядок(1000) settlement_desc - рядок(1000) transaction_id - ціле(12)	settlement_date АБО tran_time АБО payment_id	[ { "s": "settlement_date", "m": "dateis", "v": "2019-01-24" } ]	Звіт про розрахунки non-EU
500	chargeback_createtime - datetime(YYYY-MM-DD HH24:MI:SS) tran_id - integer(12) sender_email - string(1000) status - string(1000) tran_timestart - datetime(YYYY-MM-DD HH24:MI:SS) tran_timeend - datetime(YYYY-MM-DD HH24:MI:SS) tran_type - string(1000) protocol - string(1000) currency - string(3) amount - decimal(19,2) payout_date - datetime(YYYY-MM-DD HH24:MI:SS) payout_amoun - datetime(YYYY-MM-DD HH24:MI:SS)	tran_id АБО chargeback_createtime	[ { "on_page": 5, "page": 1, "filters": [ { "s": "chargeback_createtime", "m": "from", "v": "2019-12-11" }, { "s": "chargeback_createtime", "m": "to", "v": "2019-12-13" } ], "merchant_id": 1396424, "report_id": "500" } ]	Звіт про чарджбеки
528	tran_id - integer(12) parent_tran_id - integer(12) sender_email - string(1000) status - string(1000) tran_timestart - datetime(YYYY-MM-DD HH24:MI:SS) tran_timeend - datetime(YYYY-MM-DD HH24:MI:SS) tran_type - string(1000) currency - string(3) actual_amount - decimal(19,2) payout_date - datetime(YYYY-MM-DD HH24:MI:SS) payout_amoun - decimal(19,2) order_desc - string(1000) checkout_url - string(1000)	tran_id АБО tran_timestart	[ { "on_page": 5, "page": 1, "filters": [ { "s": "tran_timestart", "m": "from", "v": "2019-12-11" }, { "s": "tran_timeend", "m": "to", "v": "2019-12-13" } ], "merchant_id": 1396424, "report_id": "528" } ]	Звіт про успішні транзакції
745	payment_id - integer(12) order_timestart - datetime(YYYY-MM-DD HH24:MI:SS) order_timeend - datetime(YYYY-MM-DD HH24:MI:SS) order_status - string(1000) amount - decimal(19,2) actual_amount - decimal(19,2) currency - string(3) actual_currency - string(3) order_type - string(1000) approval_code - string(6) card_bin - string(6) eci - string(2) fee - decimal(19,2) masked_card - string(19) order_id - string(1000) payment_system - string(1000) response_code - integer(4) response_description - string(1000) reversal_amount - decimal(19,2) rrn - string(1000) sender_email - string(1000) settlement_amount - decimal(19,2) settlement_currency - string(3) settlement_date - datetime(YYYY-MM-DD HH24:MI:SS) merchant_data - string(1000) order_desc - string(1000)	order_timestart АБО order_timeend АБО payment_id АБО order_id	[ { "on_page": 5, "page": 1, "filters": [ { "s": "order_timestart", "m": "from", "v": "2019-12-11" }, { "s": "order_timestart", "m": "to", "v": "2019-12-13" } ], "merchant_id": 1396424, "report_id": "745" } ]	Звіт про всі транзакції