API FONDYVersion 1.0

API for requesting custom reports

API general
Access token
Obtain report data
Use filters
List of available reports

API general

All requests are sent over HTTPS with POST method.

Request and response format is JSON.

The response JSON structure is always a dict (associative array).

If the err_code or error key is present, the request is not completed. In this case, err_code and error parameter in response is a error description message.

Key error codes:
Authorization token required – the token is not passed in the request header
Invalid auth token – the token is either invalid or outdated
Merchant not found – merchant not found
you have no access to this report – either report_id is invalid or you have no access to the report

Example of response in case of error:

{
   "error": "Authorization token required",
   "err_code": "Authorization token required"
}

The authorization token must be sent in the Authorization HTTP header of your request. Example:

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

Access token

Send a POST request to endpoint:

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

passing data in the form of an associative array:

Parameter	Type	Description	Example
`application_id`	string(20)	Company ID. Please refer FONDY support to obtain ID and secret key. mandatory	1234
`date`	string(1024)	Date in any format. Date is a salt for sha512 signature hash mandatory	2020-04-06 11:15:27 or 1586171872 or any other string
`signature`	string(128)	Signature mandatory	7eec02ed1088b47da639549a109c0e98a75e2d8c76dfa33db4ee18359b2ea677dda37516abc0e439b286261a48d49d3e2fd885d9f09c8ff5c7308afe4180688a

The signature is formed by concatenating the company private key, company id, and date parameter through a vertical bar | (in utf-8 encoding). From the received line, you need to take the sha512 hash in hex.

Examples of obtaining a signature.

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)));

Example of curl-request:

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

If successful, the token will be contained in the token parameter of the response JSON and will expire in 1 hour:

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

Otherwise, the response will contain the keys error_code and error_message.

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

Obtain report data

The request is sent by POST to the endpoint: https://portal.fondy.eu/api/extend/company/report/

Request parameters:

Parameter	Type	Description	Example
`filters`	JSON objects[]	A set of filters, individual within each report (report_id) mandatory	“filters”: [ { “s”: “settlement_date”, “m”: “dateis”, “v”: “2019-01-24” } ]
`merchant_id`	integer(12)	Merchant unique ID. Generated by FONDY during merchant registration. mandatory	1396424
`report_id`	integer(12)	Report unique ID (see List of available reports) mandatory	500
`on_page`	integer(12)	The limit of records that are returned in the context of single request (from 10 to 500 recommended) mandatory	500
`page`	integer(12)	Records page offset. For example, with on_page = 50, to get data from 51 to 100, you need to pass page = 2 mandatory	2

Response parameters:

Parameter	Type	Description	Example
`data`	JSON objects[][]	Dataset as a sorted two-dimensional JSON array	“data”: [ [ 1234567890, 10000000001 ], [ 1234567891, 10000000002 ] ]
`fields`	string[]	List of returned fields	“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)	Number of records in the full data set	500
`rows_on_page`	integer(12)	Number of records returned in the context of this request	50
`rows_page`	integer(12)	Range offset in the full data set. For example, if rows_on_page = 50 and rows_page = 2, then records from 51 to 100 are returned in the context of this request	2

Request example:

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

Response example:

{
  "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
}

Use filters

Filter is an array of JSON objects.

Each filter object must contain following attributes:

s – field name, to which the filter is applied
m – search operand (=, <, > etc., depending on field type )
v – field value to be filtered

Filter example

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

Operands depending on field type:

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’

Unobvious search modes:

any:
{“s”: “id”, “m”: “=”, “v”: “10,20,30”} – filter values specified with comma separator

filter is applied as id in (10,20,30)

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

filter is applied as timestart >= ‘2020-01-10’

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

filter is applied as timestart >= now() – 2 days

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

filter is applied as timestart < ‘2020-01-11‘

dateis – “daye equal” – data filtered from specified day start (00:00) till next day start (00:00) (not including next day)
like – filters partial fragment match
!like – partial fragment must not match
start – “starting from”

List of available reports

Report ID	Fields	Mandatory filter fields	Filter example	Example
666	merchant_order_id - string(1000) payment_id - integer(12) authorization_date - datetime(YYYY-MM-DD HH24:MI:SS) operation_type - string(1000) odbref - string(1000) amount - decimal(19,2) order_description - string(1000) currency - string(3) fee_currency - string(3) transaction_rate - decimal(19,6) settlement_rate - decimal(19,6) fee_rate - decimal(19,6) gross - decimal(19,2) commission - decimal(19,2) batch_number - integer(12) settlement_amount - decimal(19,2) url - string(1000) settlement_date - datetime(YYYY-MM-DD HH24:MI:SS) rolling_reserve_amount - decimal(19,2) rolling_reserve_currency - string(3) rolling_reserve_settlement_date - datetime(YYYY-MM-DD HH24:MI:SS) deposit_setllement_amount - decimal(19,2) settlement_currency - string(3) merchant_data - string(1000)	settlement_date OR authorization_date OR payment_id	[ { "s": "settlement_date", "m": "dateis", "v": "2019-01-24" } ]	Settlements report EU
403	payment_id - integer(12) order_time - datetime(YYYY-MM-DD HH24:MI:SS) order_status - string(1000) actual_amount - decimal(19,2) currency - string(3) fee - decimal(19,2) order_id - string(1000) settlement_amount - decimal(19,2) settlement_currency - string(3) settlement_date - datetime(YYYY-MM-DD HH24:MI:SS) settlement_status - string(1000) odb_ref - string(1000) tran_time - datetime(YYYY-MM-DD HH24:MI:SS) settlement_type - string(1000) payment_system - string(1000) sender_email - string(1000) order_desc - string(1000) merchant_data - string(1000) settlement_desc - string(1000) transaction_id - integer(12)	settlement_date OR tran_time OR payment_id	[ { "s": "settlement_date", "m": "dateis", "v": "2019-01-24" } ]	Settlements report 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 OR 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" } ]	Chargebacks report
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 OR 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" } ]	Success transactions report
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 OR order_timeend OR payment_id OR 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" } ]	All transactions report