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 of a request header with access token

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

Authentication¶

Before getting data from report, you need to obtain access token.

A JSON POST request should be sent to endpoint: https://portal.flitt.com/authorizer/token/application/get

Parameters of authentication request

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

The signature is formed by concatenating the application private key, application id, and date parameter through a vertical bar | (in utf-8 encoding).

Sha512 hash function should be applied to the resulting string.

Code example of obtaining a signature

pythonphp

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
$date = strtotime("now");
$company_id = %application_id%;
$signature = hash('sha512', join('|',array('%your_company_private_key%', $company_id, $date)));

If request is successful, the token will be contained in the token parameter of the JSON response and will expire in 1 hour Otherwise, the response will contain the keys error_code and error_message.

Example of curl request

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

Example of response in case of error

success responseresponse with error

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

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

Obtain report data¶

The request should be sent as POST to the endpoint: https://portal.flitt.com/api/extend/company/report/

Parameters of request of obtaining report data

Request parametersResponse parameters

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

Parameter	Mandaroty	Type	Description	Example
`data`	mandatory	JSON objects[][]	Dataset as a sorted two-dimensional JSON array	“data”: [ [ 1234567890, 10000000001 ], [ 1234567891, 10000000002 ] ]
`fields`	mandatory	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`	mandatory	integer(12)	Number of records in the full data set	500
`rows_on_page`	mandatory	integer(12)	Number of records returned in the context of this request	50
`rows_page`	mandatory	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

Example of request and response

RequestResponse

curl 'https://portal.flitt.com/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,
      "2025-01-23 10:58:38",
      "approved",
      "630.00",
      "GEL",
      "11.97",
      "test-25697841-1",
      "618.03",
      "EUR",
      "2025-01-24 08:00:00",
      "completed",
      "2426012568",
      "2025-01-23 10:58:38",
      "purchase",
      "Visa/MC",
      "test@test.com",
      "Test order 1",
      "[]",
      "Test payment 1",
      10000000001
    ],
    [
      1234567891,
      "2025-01-23 10:56:51",
      "approved",
      "572.86",
      "GEL",
      "10.88",
      "test-94341241-1",
      "561.98",
      "EUR",
      "2025-01-24 08:00:00",
      "completed",
      "2426012568",
      "2025-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¶

Example

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¶

Example

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¶

Parameters of request of obtaining report data

Report ID	Fields	Mandatory filter fields	Filter example	Description
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