API FONDYVersion 1.0

API for requesting custom reports

The previous version of report API is deprecated.

  1. API general
  2. Access token
  3. Obtain report data
  4. Use filters
  5. 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://wallet.fondy.eu/authorizer/token/application/get

passing data in the form of an associative array:

ParameterTypeDescriptionExample
application_idstring(20)Company ID. Please refer FONDY support to obtain ID and secret key.

mandatory
1234
datestring(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
signaturestring(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://wallet.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:

ParameterTypeDescriptionExample
filtersJSON objects[]A set of filters, individual within each report (report_id)

mandatory
“filters”: [ { “s”: “settlement_date”, “m”: “dateis”, “v”: “2019-01-24” } ]
merchant_idinteger(12)Merchant unique ID. Generated by FONDY during merchant registration.

mandatory
1396424
report_idinteger(12)Report unique ID (see List of available reports)

mandatory
500
on_pageinteger(12)The limit of records that are returned in the context of single request (from 10 to 500 recommended)

mandatory
500
pageinteger(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:

ParameterTypeDescriptionExample
dataJSON objects[][]Dataset as a sorted two-dimensional JSON array“data”: [ [ 1234567890, 10000000001 ], [ 1234567891, 10000000002 ] ]
fieldsstring[]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_countinteger(12)Number of records in the full data set500
rows_on_pageinteger(12)Number of records returned in the context of this request50
rows_pageinteger(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 request2

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 IDFieldsMandatory filter fieldsFilter exampleExample
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
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

 

Connect to FONDY and learn more!