Retrieving data

The following endpoints in the Data API are used to retrieve data:

• /balance/get—to retrieve balance information (currently available only for OUT balances)
• /chargeback/list—to retrieve chargeback information filtered by specified conditions
• /chargeback/get—to retrieve information about a single chargeback
• /fraud/list—to retrieve information about operations flagged as fraudulent
• /operations/get—to retrieve operation information filtered by specified conditions
• /opearations/get-by-payment—to retrieve information about operations initiated within a specific payment
• /currency-rates/get—to retrieve reference information on currency conversion rates applied to financial transactions

The general procedure of sending requests to any of these endpoints is the same as described in previous articles of this section. This article covers special aspects of using these requests and complements the description of data structures in the interface specification.

Requests to retrieve balance information on the merchant's projects should be sent to the /balance/get endpoint.

These requests must contain parameters token (a token associated with the specific user account) and signature. Responses to such requests contain information about the current state of OUT balances.

Information about each balance includes the balance type and the available total sum in this balance's currency. The currency is specified in the name of the parameter and the sum is passed as its value ("<currency>": "<sum>").

// Request body
{
  "token":"ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
  "signature":"dQcIbv94Z0nPTYX9glSCi...jqInXqYrY9bzkfcBGQ=="
}

// Response body
{
    "balance": [
        {
            "name": "Project_Cosmo1_balance_AUD",
            "AUD": "1010750"
        },
        {
            "name": "Project_Cosmo1_balance_USD",
            "USD": "310099"
        },
        {
            "name": "Project_Cosmo1_balance_EUR",
            "EUR": "113128"
        }
    ],
    "signature": "3XOq69...OKvPLwQQrRtwxFy5gTz1ggQkoMK9tw5w=="
}

Requests to retrieve chargeback information filtered by specified conditions should be sent to the /chargeback/list endpoint.

When sending such requests, consider the following:

1. These requests must contain parameters token (a token associated with the specific user account with the Risks or Merchant Admin role and with the access rights to certain projects of the merchant) and signature.

2. To filter information about chargebacks by different parameters, use the filter object.

   In the filter object, any date range must be an object defined by from and to string parameters. The rest of parameters can be an array of one or more values or a string of values separated with a comma and a space (provider_id can be only an array). Parameters in the filter object can be listed in an arbitrary order. By default, if the request does not contain these parameters, the payment platform returns chargeback information on all of the projects that can be accessed with the use of the token.

   The filter object can include the following objects and parameters:

   • report_date—a date range with date values in the format "YYYY-MM-DD"; refers to the time when the information about the chargeback was received in the payment platform
   • respond_by—the deadline for submitting a response to the chargeback (must be specified as a date range with date values in the format "YYYY-MM-DD HH-MM-SS" where time can be skipped)
   • chb_completed_at—the date when the chargeback received one of the final statuses (must be specified as a date range with date values in the format "YYYY-MM-DD HH-MM-SS" where time can be skipped)
   • project_id—project ID provided by ecommpay
   • chargeback_id—chargeback ID provided by ecommpay
   • chargeback_stage—chargeback stage (Chargeback, Representment, Pre-Arbitration attempt, Pre-Arbitration response, or Arbitration; details)
   • arn—acquirer reference number used for clearing
   • card—card number used by the customer to make the disputed payment
   • card_type—the code of the payment system (visa for Visa and mc for Mastercard);
   • reason_code—numerical chargeback reason code provided by the payment system
   • operation_id—ID of the disputed operation provided by ecommpay
   • status—current status of the chargeback
3. To restrict the number of chargebacks the information about which is returned in a single response, use the pagination object with two parameters: limit and offset. The limit parameter is used to set the number of the returned operations in the response (more than 1). The offset parameter is used to retrieve the subset of chargebacks beginning with the number that follows the offset value (counting starts from 0). For example, if you need to retrieve information about chargebacks 21-25, you should set "limit": 5 and "offset": 20 in the request. If these parameters are absent, the default values are 20 for limit and 0 for offset.

Responses to such requests contain chargeback data with the consideration of the conditions determined in the request.

// Body of the request:
{
    "token": "ZOyTL5shYsdhpxdQdfdfJYmGV7Kv",
    "filter": {
        "report_date"{
            "from": "2022-01-01",
            "to": "2022-02-01"
        }
        "status": [
            "WON",
            "PARTIALLY WON"
        ]
    },
    "signature": "DNqOZOCxNlXu3bENrDPuEE8fSJLWDNM/CE8Xjj9...VcNFw=="
}

// Body of the response:{
  "operations": [
    {
      "chargeback_id": "11201",
      "charged_amount": "5000",
      "channel_amount": "5000",
      "case_id": "142",
      "project_id": "1234",
      "operation_id": "12330123485431",
      "report_date": "2022-01-31",
      "respond_by": "2022-02-04 23:59:59",
      "rev_date": null,
      "tr_date_time": "2022-01-13 17:00:56",
      "chb_completed_at": "2022-02-21 00:00:00",
      "chb_amount": "50.00",
      "chb_settlement_amount": "50.00",
      "rev_indicator": null,
      "chb_ccy": "USD",
      "chb_settlement_ccy": "USD",
      "charged_currency": "USD",
      "channel_currency": "USD",
      "eci_sli": "7",
      "reason_code": "10.4",
      "card_type": "VISA",
      "merchant_id": "10000123",
      "card": "431422******0056",
      "arn": "74312342013012340041234",
      "status": "WON",
      "chb_amount_in_usd": "50.0000",
      "merchant_name": "Cosmoshop_on_Mars",
      "order_id": "1234123412345",
      "operation_type": "sale",
      "auth_code": "061230",
      "card_holder": "JANE DOE",
      "issuer_country": "UK",
      "issuer_country": "UK",
      "chargeback_stage": "Arbitration",
      "pre_arbitration_report_date": "2022-02-06",
      "pre_arbitration_amount": "50.00",
      "pre_arbitration_ccy": "USD",
      "arbitration_report_date": "2022-03-06",
      "arbitration_amount": "50.00",
      "arbitration_ccy": "USD",
      "representment_amount": "50.00",
      "representment_ccy": "USD"
    },
    ...
  ],
  "signature": "k4iXC84dfwevT+...dS056fssBGIw=="
}

A request to retrieve single chargeback information should be sent to the /chargeback/get endpoint.

When sending such requests, consider the following:

1. The request must contain parameters token (a token associated with the specific user account with the Risks or Merchant Admin role and with the access rights to certain projects of the merchant) and signature.
2. The request must contain one of the following identifiers in the filter object:
   • chargeback_id—chargeback ID provided by ecommpay
   • arn—acquirer reference number used for clearing
   • operation_id—operation ID provided by ecommpay

The response to such request contains information about the required chargeback.

// Body of the request:
{
  "token": "ZOyTL5shYsdhpxdQdfdfJYmGV7Kv",
  "filter": {
        "operation_id": 87980010093051
    },
  "signature": "VoOJxpMge0uBN22gZxf3BhE+5wlCaU...y+KM1lQ=="
}

// Body of the response:

{
  "chargeback": {
    "chargeback_id": "11201",
    "charged_amount": "5000",
    "channel_amount": "5000",
    "case_id": "142",
    "project_id": "1234",
    "operation_id": "12330123485431",
    "report_date": "2022-01-31",
    "respond_by": "2022-02-04 23:59:59",
    "rev_date": null,
    "tr_date_time": "2022-01-13 17:00:56",
    "chb_completed_at": "2022-02-21 00:00:00",
    "chb_amount": "50.00",
    "chb_settlement_amount": "50.00",
    "rev_indicator": null,
    "chb_ccy": "USD",
    "chb_settlement_ccy": "USD",
    "charged_currency": "USD",
    "channel_currency": "USD",
    "eci_sli": "7",
    "reason_code": "10.4",
    "card_type": "VISA",
    "merchant_id": "10000123",
    "card": "431422******0056",
    "arn": "74312342013012340041234",
    "status": "WON",
    "chb_amount_in_usd": "50.00",
    "merchant_name": "Cosmoshop_on_Mars",
    "order_id": "1234123412345",
    "operation_type": "sale",
    "auth_code": "061230",
    "card_holder": "JANE DOE",
    "issuer_country": "UK",
    "chargeback_stage": "Arbitration",
    "pre_arbitration_report_date": "2022-02-06",
    "pre_arbitration_amount": "50.00",
    "pre_arbitration_ccy": "USD",
    "arbitration_report_date": "2022-03-06",
    "arbitration_amount": "50.00",
    "arbitration_ccy": "USD",
    "representment_amount": "50.00",
    "representment_ccy": "USD"
  },
  "signature": "lSiQYO06cTBi5Hos2/sWjWOZocZhDr...gtmmKfB2g=="
}

A request to retrieve information about operations flagged as fraudulent by payment systems should be sent to the /fraud/list endpoint (information about operations flagged as fraudulent by ecommpay is not provided in the response to this request).

When sending such requests, consider the following:

1. The request must contain parameters token (a token associated with the specific user account with the Risks or Merchant Admin role and with the access rights to certain projects of the merchant) and signature.
2. The request may contain the filter object with any of the following parameters:
   • received_on—date when the payment system reported the fraudulent operation (must be specified as a date range)
   • purchase_date—date when the operation was completed (must be specified as a date range)
   • fraud_report_date—date when the operation was reported as fraudulent to the issuing bank (must be specified as a date range)
   • issuer_country—country of the issuer determined according to the BIN of the card in ISO 3166-1 alpha-2 format

   The date range in this filter object must contain start and end dates and must be specified as a string array, for example, "purchase_date": ["2021-12-31 00:00:00", "2022-01-07 23:59:59"].

3. To restrict the number of operations the information about which is returned in a single response, use the pagination object with two parameters: limit and offset. The limit parameter is used to set the number of the returned operations in the response (more than 1). The offset parameter is used to retrieve the subset of operations beginning with the number that follows the offset value (counting starts from 0). For example, if you need to retrieve information about fraudulent operations 21-25, you should set "limit": 5 and "offset": 20 in the request. If these parameters are absent, the default values are 20 for limit and 0 for offset.

Responses to such requests contain operation data filtered by the conditions determined in the request.

// Body of the request:
{
  "token": "ZOyTL5shYsdhpxdQdfdfJYmGV7Kv",
  "signature": "dfsder34fuk7sJ...grdfht5gJg==",
  "filter": {
    "received_on": [
      "2022-01-01 00:00:00",
      "2022-02-01 23:59:59"
    ]
    "issuer_country": [
      "GB"
    ]
  },
  "pagination": {
    "limit": 5,
    "offset": 20
  }
}

// Body of the response:{
  "operations": [
    {
      "payment_id": "cosmopayment78",
      "operation_id": 6435212169999,
      "tr_amount": "580.00",
      "tr_ccy": "USD",
      "account_number": "431422******0056",
      "payment_method_type": "visa",
      "row_updated_at": "2022-01-01 05:30:30",
      "customer_id": "earthling1232400",
      "project_name": "cosmoshop.earth",
      "project_id": "123",
      "arn": "40216364365007272011473",
      "fraud_type": "6",
      "fraud_report_date": "2022-02-10",
      "issuer_country": "GB",
      "received_on": "2022-02-11",
      "purchase_date": "2022-02-01",
      "channel_amount_in_usd": "580.00",
      "issuer_bank_name": "Intergalactic Bank",
      "bin": "123456",
      "country_by_ip": "GB",
      "customer_email": "earthling@earth.earth",
      "report_and_purchase_date_difference": 9
    }
  ],
  "signature": "k4iXC84dfwevT+...dS056fssBGIw=="
}

Requests to retrieve operation information for a specified time period on the merchant's projects should be sent to the /operations/get endpoint.

When sending such request, consider the following:

1. The request must contain the following objects and parameters:
   • interval—an object with the specified start and end dates of the time period over which the target operations were updated following the most recent actions:
     • from—start date and time of the interval, in YYYY-MM-DD hh:mm:ss format
     • to—end date and time of the interval, in YYYY-MM-DD hh:mm:ss format
     Note: If more than one request is received in the platform from a single Dashboard user account within 10 seconds and the time period (interval) for which the information is requested exceeds 180 days, these requests are processed one by one, with 10 seconds timeouts.
   • token—a token associated with the specific user account
   • signature—a request signature generated after all required parameters have been specified.
2. To filter operations by project, use the project_id parameter. Keep in mind that the access rights associated with the token passed in the request also factor in what data is going to be returned. By default, if the request does not contain this parameter, the payment platform returns operation information on all of the projects which can be accessed with the use of the token. If you need operation data for specific projects (one or several), specify the identifiers of these projects in the project_id parameter (separated with a comma and a space: for example, 4, 12).
3. To specify a time zone different from the default UTC +00:00, use the tz parameter. The time zone specified with the help of this parameter affects what operations will be selected for the time period specified in the interval object and the format of the date and time parameters in the response—for example, operation_created_at and operation_completed_at. In the tz parameter, the time zone is specified in the UTC offsets format (for example, +10:30) or in the IANA Time Zone Database format (for example, Asia/Singapore).

4. To restrict the number of operations information about which is returned in a single response, use the limit parameter. This parameter can take a value between 0 and 1000. By default, it is set to 1000, while the number of the returned operations in the response can be lower than the specified value.

   If you need information about more than one thousand operations, send several requests with the offset parameter specified in each. This parameter determines the offset value for selecting operations. When both limit and offset parameters are passed in the request, then the number of the operations included in the first response equals the value of the offset parameter, and the remaining number of operations returned in the second response does not exceed the value of the limit parameter.

   For example, if you need to retrieve operation data on 1125 operations, then you can specify the following values for the limit and offset parameter in the requests: "limit": "1000" and "offset": "0" in the first one, "limit": "125" and "offset": "1000" in the second one.

5. To restrict the number of operations returned in a single response, use the limit parameter with a value between 0 and 1000. If you need information about more than one thousand operations, send several requests with the offset parameter specified in each. This parameter determines the offset value for selecting operations.

6. To filter operation data by various parameters, use the fields array. By default, if the request does not contain this array, the payment platform returns the predefined set of data for each operation. If you need specific information (related to one or more specific parameters), pass the names of these parameters in the fields array.

   Parameters in the array are separated with a comma and a space (if you need more than one) and can be listed in an arbitrary order. However, the order in which the data is listed in responses is fixed. The full list of parameters can be found in the Data API specification: see the list of parameters in the operations object included in the format description of the response to the request sent to the /operations/get endpoint. In this description, the parameters are listed in the default order and marked as required.

7. To filter operation data by various parameters, use the fields array. The full list of parameters can be found in the Data API specification: see the list of parameters in the operations object included in the format description of the response to the request sent to the /operations/get endpoint.

8. To retrieve operation data by certain operation types and/or statuses, use the operation_type and operation_status arrays. By default, if the request does not contain these arrays, the payment platform returns operation data for all operation types and statuses. Specify operation types and statuses needed in the operation_type and operation_status arrays. Separate multiple elements within the arrays by a comma with a space if necessary. The comprehensive list of operation types and statuses can be found in Payment models and statuses.

   The operation_type and operation_status parameters can be passed as arrays (if you need to pass one or more values) and as strings (if you need to pass a single value).

9. To filter operation data by customer IDs and/or customer emails, use the customer_id array and customer_email string parameters. By default, if the request does not contain these parameters, the payment platform returns operation data with no regard for customer IDs and emails.

   The customer_id parameter can be passed as an array (if you need to pass one or more values) and as a string (if you need to pass a single value).

Responses to such requests contain operation data for a specified time period with the consideration of the conditions determined in the request.

If the default set of parameters is enough, there is no need to pass the fields array in the requests.

// Body of the request to retrieve data on 1000 operations (starting from 0) 
{
  "project_id":[
    0,
    1
  ],
  "interval": {
    "from":"2020-08-01 00:00:00",
    "to":"2020-08-28 23:59:59"
  },
  "limit":"1000",
  "offset": "0",
  "token":"ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
  "signature":"yPu0wYr2BoV5...MzQtRkvdC0y=="
}

// Body of the request to retrieve data on subsequent 125 operations (starting from 1000)
{
  "project_id":[
    0,
    12
  ],
  "interval": {
    "from":"2020-08-01 00:00:00",
    "to":"2020-08-28 23:59:59"
  },
  "limit":"125",
  "offset": "1000"
  "token":"ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
  "signature":"sd0fr5YsdBVmJ...grkglpeXJg=="
}

// Body of the response to the first request
{
    "operations": [
        // information about the operation
        { 
            "project_id": "11",
            "operation_id": "6435212162442",
            "payment_id": "EP06c1-b285",
            "operation_type": "sale",
            "operation_status": "success",
            "account_number": "431422******0056",
            "customer_ip": "87.245.207.226",
            "payment_method_name": "visa",
            "payment_method_type": "visa",
            "payment_description": "",
            "operation_created_at": "2018-08-01T08:28:47+00:00",            
            "provider_date": "2020-08-01 10:34:24",
            "shipment_date": "",
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "USD"
            },
            "arn": "12304191169003210000234",
            "rrn": "001045563840",
            "payment_provider_code": "0",
            "payment_provider_message": "Success"
        },

        // information about another operation
        { 
            "project_id": "11",
            "operation_id": "6435212162442",
            "payment_id": "EP06c1-b285",
            "operation_type": "sale",
            "operation_status": "success",
            "account_number": "431422******0056",
            "customer_ip": "87.245.207.226",
            "payment_method_name": "visa",
            "payment_method_type": "visa",
            "payment_description": "",
            "operation_created_at": "2018-08-01T08:28:47+00:00",
            "provider_date": "2018-02-07 10:34:24",
            "shipment_date": "",
            "sum_initial": {
                "amount": 1000,
                "currency": "USD"
            },
            "sum_converted": {
                "amount": 1000,
                "currency": "USD"
            },
            "arn": "30407191169003210010678",
            "rrn": "128905563823",
            "payment_provider_code": "0",
            "payment_provider_message": "Success"
        },
        // information about the rest of the operations
        ...
    ],
    "signature": "k4iXC845FvT+HdWdxMkXAV8dS0AH5BGIw=="
}

If you need to customise the standard set of parameters included in operation data, you can specify the required parameters in the fields array. If, in addition, you need to filter operation data, specify filtering criteria by using such parameters as operation_type, opeartion_status and customer_email.

// Body of the request:
{
    "project_id":[
        0,
        11
    ],
    "interval": {
        "from":"2021-07-01 00:00:00",
        "to":"2021-07-19 23:59:59"
    },
    "operation_type": [
        "sale",
        "refund"
    ],
    "operation_status": [
        "success",
        "decline"
    ],
    "customer_email": "astronaut@earth.station",
    "token":"qOnHY86dfhpxdghEBb7HSLbe",
    "fields": [
        "operation_id",
        "operation_type",    
        "operation_status",
        "sum_initial.amount",
        "sum_initial.currency",
        "customer_email"
    ],
    "signature":"vtv5TN6aWQV...5QBjpe8Dsv=="
}

// Body of the response:

{
    "operations": [
    // information about the operation
    {
        "operation_id": "12347892",
        "operation_type": "sale",
        "operation_status": "success",
        "sum_initial": {
            "amount": 1000,
            "currency": "USD"
        },
        "customer_email": "astronaut@earth.station"
    },
    // information about another operations ...
    ],
    "signature": "sdkf45rt73jncpEB75HTS=="
}

Requests to retrieve information about operations initiated within a specific payment should be sent to the /operations/get-by-payment endpoint.

These requests must contain parameters payment_id (ID of the target payment), token (a token associated with the specific user account), and signature. Responses to such requests contain information about the operations initiated within the target payment.

// Request body
{
  "payment_id":"PID_25467851461-2147",
  "token":"VmJQhaXILAnZWTKmqwSd3j",
  "signature":"JM+YWmTL7uGn26IgZWTKmqwSd3jJM+YWmTL7uGn26IglUOMzQtRkvdC0yaq030+eNXVtJjjtgrkglpeXJg=="
}

// Response body
{
  "operations": [
    {
      "arn": "",
      "operation_completed_at": "2019-11-22T13:13:04+00:00",
      "operation_type": "refund",
      "operation_id": "2747253065470",
      "amount": 221,
      "currency": "USD",
      "operation_created_at": "2019-11-22T13:13:04+00:00",
      "rrn": "803817399309",
      "payment_provider_code": "0",
      "payment_provider_message": "Success"
    },
    {
      "arn": "",
      "operation_completed_at": "2019-11-22T13:09:03+00:00",
      "operation_type": "capture",
      "operation_id": "2747253065469",
      "amount": 1621,
      "currency": "USD",
      "operation_created_at": "2019-11-22T13:09:03+00:00",
      "rrn": "000000248370",
      "payment_provider_code": "0",
      "payment_provider_message": "Success"
    },
    {
      "arn": "",
      "operation_completed_at": "2019-11-22T13:06:40+00:00",
      "operation_type": "auth",
      "operation_id": "2747253065468",
      "amount": 200,
      "currency": "USD",
      "operation_created_at": "2019-11-22T13:06:38+00:00",
      "rrn": "000047769105",
      "payment_provider_code": "0",
      "payment_provider_message": "Success"
    }
  ],
  "signature": "hsUpqn7QPDxNLNH/ZulaK6ICiH7bABSdjLPkQXkMjQ7tqoB8TCJR1Oh2xyiA8y1WihDJ4ljz/Hv7NkQFujSnvw=="
}

Requests to retrieve information on currency conversion rates applied to operating and non-operating inflows and outflows in the payment platform should be sent to the /currency-rates/get endpoint. Conversion rates information is provided for reference use only.

Responses to such requests contain approximate sell and buy rates for the specific currency against the US dollar estimated at the beginning of each hour within the given time period. In addition, for some currencies (Bulgarian lev (BGN), for example) responses will include conversion rates of this currency to euro (EUR).

The request to the /currency-rates/get endpoint must contain the following objects and parameters:

• token—a token associated with the specific user account that has permissions to access all required projects.
• signature—a request signature generated after all required parameters have been specified.
• filter—an object with parameters to filter currency conversion rates by:
  • merchant—an internal identifier of the merchant in the payment platform provided by the ecommpay technical support upon request (specified as an integer, for example, 97).
  • currency—the code of the required currency in the ISO-4217 alpha-3 format (learn more).
  • interval—an object with the specified start and end dates of the time period:
    • from—start date and time of the interval, in YYYY-MM-DD hh:mm:ss format.
    • to—end date and time of the interval, in YYYY-MM-DD hh:mm:ss format.
    Note: If the specified time period is less than one hour (including cases when start and end times match), the retrieved conversion rates data will be relevant for the time specified in the from parameter. If the specified time period is invalid (set in the future, for example), the response to such request will not contain conversion rates data.
• tz—time zone specified in the UTC offsets format (for example, +10:30) or in the IANA Time Zone Database format (for example, Asia/Singapore).

// Request body
{
  "token":"VmJQhaXILAnZWTKmqwSd3j",
  "signature":"JM+YWmT...peXJg==",
  "filter": {
    "merchant": 1,
    "currency": "BGN",
    "interval": {
      "from": "2023-11-14 12:00:00",
      "to": "2023-11-14 13:00:00"
    },
  "tz":"Asia/Singapore"
  }
}

// Response body

{
    "rates": [
        {
            "merchant": 1,
            "currency": {
                "from": "USD",
                "to": "BGN"
            },
            "rates": {
                "date": "2023-11-14 12:00:00",
                "sellRate": "1.831926",
                "buyRate": "1.832200"
            }
        },
        {
            "merchant": 1,
            "currency": {
                "from": "EUR",
                "to": "BGN"
            },
            "rates": {
                "date": "2023-11-14 12:00:00",
                "sellRate": "1.955653",
                "buyRate": "1.955947"
            }
        }
    ],
    "signature": "8MrtPTHV7tB0....3jKEHTEbZVCqA=="
}