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
• /financial-reporting/operations—to retrieve itemised operation data for financial reporting (including charged fees) for a specified time period
• /operations/get—to retrieve itemised operation data for a specified time period
• /operations/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 Dashboard user account) and signature (details). 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 Dashboard user account with the Risks or Merchant Admin role and with the access rights to certain projects of the merchant) and signature (details).

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": "2024-01-01",
            "to": "2024-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": "2024-01-31",
      "respond_by": "2024-02-04 23:59:59",
      "rev_date": null,
      "tr_date_time": "2024-01-13 17:00:56",
      "chb_completed_at": "2024-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": "2024-02-06",
      "pre_arbitration_amount": "50.00",
      "pre_arbitration_ccy": "USD",
      "arbitration_report_date": "2024-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 Dashboard user account with the Risks or Merchant Admin role and with the access rights to certain projects of the merchant) and signature (details).
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": "2024-01-31",
    "respond_by": "2024-02-04 23:59:59",
    "rev_date": null,
    "tr_date_time": "2024-01-13 17:00:56",
    "chb_completed_at": "2024-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": "2024-02-06",
    "pre_arbitration_amount": "50.00",
    "pre_arbitration_ccy": "USD",
    "arbitration_report_date": "2024-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 Dashboard user account with the Risks or Merchant Admin role and with the access rights to certain projects of the merchant) and signature (details).
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": ["2023-12-31 00:00:00", "2024-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": [
      "2024-01-01 00:00:00",
      "2024-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": "2024-01-01 05:30:30",
      "customer_id": "earthling1232400",
      "project_name": "cosmoshop.earth",
      "project_id": "123",
      "arn": "40216364365007272011473",
      "fraud_type": "6",
      "fraud_report_date": "2024-02-10",
      "issuer_country": "GB",
      "received_on": "2024-02-11",
      "purchase_date": "2024-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 itemised operation data for financial reporting (including charged fees) for a specified time period should be sent to the /financial-reporting/operations endpoint. This information can complement the operation data retrieved for general purposes (details) and used for final analysis and reconciliation.

When sending a request to retrieve itemised operation data for financial reporting, consider the following:

When sending such request, consider the following:

1. The request must contain the following objects and parameters:
   • token—a token associated with the specific Dashboard user account
   • signature—a request signature generated after all required parameters have been specified (details)
   • operation_completed_at—an object that defines the time period over which the required operations were finalised (with the most recent actions and updates taken into consideration):
     • from—start date and time of the interval, in the YYYY-MM-DD hh:mm:ss format
     • to—end date and time of the interval, in the YYYY-MM-DD hh:mm:ss format
     Note: You can only request data about operations completed in the payment platform within the last 30 days.
   • 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).
2. To filter operations by projects and/or providers, use the project_id and provider_id arrays. 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 these arrays, the payment platform returns operation information on all of the projects (which can be accessed with the use of the token) and on all of the providers involved in performing these operations. If you need operation data for specific projects and providers, specify their identifiers in the project_id and provider_id arrays (separated with a comma and a space: for example, 4, 12).
3. To filter operation data by operation identifiers, use the operation_id array. By default, if the request does not contain this array, the payment platform returns itemised data for all operations that otherwise meet the query criteria. If you need operation data for specific operations, pass their identifiers in the operation_id array (separated with a comma and a space: for example, 6435212162442, 6435212162443).

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 multiple requests with the offset parameter specified in each. This parameter determines the offset value for selecting operations. When both the limit and offset parameters are passed in the request, then the number of the operations that equals the value of the offset parameter is skipped, and the remaining number of operations returned in the 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 parameters 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 multiple requests with the offset parameter specified in each. This parameter determines the offset value for selecting operations.

Responses to such requests contain operation data for a specified time period, retrieved according to the request criteria.

// Body of the request to retrieve data on 1000 operations (starting from 0)  
{
  "project_id": [11],
  "operation_completed_at": {
    "from": "2024-09-01 00:00:00",
    "to": "2024-09-31 23:59:59"
  },
  "tz": "Indian/Mauritius",
  "limit": 1000,
  "offset": 0,
  "token": "ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
  "signature": "YsrkgdBr5peXJgJ...glVmsd0f=="
}

// Body of the response 
 
{
  "data": [
    {
      "operation_completed_at": "2024-09-29T22:08:19+0000",
      "transaction_id": "81194009089601",
      "operation_id": "81194009122865",
      "provider_payment_id": "0040000028207224",
      "payment_id": "1994-1312",
      "arn": "70114165164100000032105",
      "rrn": "451912040334",
      "auth_appr_code": "611887",
      "operation_type": "sale",
      "operation_status": "success",
      "tran_region": "domestic",
      "tariff_region": "EU",
      "proc_region": "Visa Europe",
      "security_level": "SEC",
      "operation_amount": 2098.00,
      "operation_currency": "GBP",
      "billing_conversion_rate": 0.00,
      "billing_amount": 2098.00,
      "billing_currency": "GBP",
      "total_interchange_fee": -4.20,
      "total_scheme_fee": -0.64,
      "auth_msc_fee": 0.000000,
      "clearing_msc_fee": -3.785649,
      "total_msc_fee": -3.78,
      "hold_amount": 0.00,
      "project_id": 11,
      "project_url": "https://www.company.com",
      "merchant_name": "COMPANY NAME",
      "mid": "70000000",
      "terminal_id": "70000000",
      "mcc_code": "4722",
      "legal_country": "GB",
      "payment_method_name": "visa",
      "product_type": "Consumer",
      "account_funding_source": "debit",
      "account_number": "475144******1111",
      "card_product": "Visa classic",
      "issuer_country": "GB",
      "customer_id": "1436462",
      "card_holder": "CARD HOLDER"
    },
    // information about other operations...
  ],  
  "signature": "sncpEB75H...3jTS=="
}

Requests to retrieve itemised operation data for a specified time period should be sent to the /operations/get endpoint. You can use this information for monitoring your operations and their technical analysis. To obtain accurate financial information that can be used for final analysis and reconciliation, retrieve itemised operation data for financial reporting (including charged fees; details).

When sending a request to retrieve operation data for general purposes, consider the following:

When sending such request, consider the following:

1. The request must contain the following objects and parameters:
   • token—a token associated with the specific Dashboard user account
   • signature—a request signature generated after all required parameters have been specified (details)
   • interval—an object that defines the time period over which the required operations were finalised (with the most recent actions and updates taken into consideration):
     • from—start date and time of the interval, in the YYYY-MM-DD hh:mm:ss format
     • to—end date and time of the interval, in the 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 value of the interval parameter specified in the requests exceeds 180 days, these requests are processed one by one, with 10 second delay.
2. To filter operations by project, use the project_id array. 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 array, 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, specify the identifiers of these projects in the project_id array (separated with a comma and a space if more than one identifier needed: 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 multiple requests with the offset parameter specified in each. This parameter determines the offset value for selecting operations. When both the limit and offset parameters are passed in the request, then the number of the operations that equals the value of the offset parameter is skipped, and the remaining number of operations returned in the 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 parameters 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 multiple requests with the offset parameter specified in each. This parameter determines the offset value for selecting operations.

6. If you need to retrieve specific operation data parameters, use the fields array. If the request does not contain this array, the payment platform returns the default set of data for each operation. For a customised set of data, pass the names of parameters you need in the fields array.

   The names of 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 are listed in responses is fixed. The full list of parameters can be found in the 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 fixed order that cannot be customised in responses. The parameters included in the default set of data are marked as required.

7. If you need to retrieve specific operation data parameters, use the fields array. The full list of available data can be found in the 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 parameters. By default, if the request does not contain these parameters, the payment platform returns operation data for all operation types and statuses. If you use these parameters, specify operation types and statuses that you need and separate multiple values within the arrays by a comma with a space if necessary. The comprehensive list of operation types and statuses can be found in Payment processing.

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

9. To filter operation data by customer identifiers and/or customer emails, use the customer_id and customer_email parameters. By default, if the request does not contain these parameters, the payment platform returns itemised data for all operations that otherwise meet the query criteria. The customer_id parameter can be passed as a string (if you need to pass a single value) and as an array (if you need to pass one or more values), and the customer_email parameter can only be passed as a string.

Responses to such requests contain operation data for a specified time period, retrieved according to the request criteria.

If the default set of parameters returned in responses 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":"2024-04-04 00:00:00",
    "to":"2024-04-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":"2024-04-04 00:00:00",
    "to":"2024-04-28 23:59:59"
  },
  "limit":"125",
  "offset": "1000"
  "token":"ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
  "signature":"sd0fr5YsdBVmJ...grkglpeXJg=="
}

// Body of the response to the first request
{
    "operations": [
        // information about an operation
        { 
            "project_id": "11",
            "operation_id": "6435212162442",
            "payment_id": "EP06c1-b285",
            "operation_type": "sale",
            "operation_status": "success",
            "account_number": "431422******0056",
            "customer_ip": "192.0.2.255",
            "payment_method_name": "visa",
            "payment_method_type": "visa",
            "payment_description": "",
            "operation_created_at": "2024-04-04T08:28:47+00:00",            
            "provider_date": "2024-04-04 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": "198.51.100.0",
            "payment_method_name": "visa",
            "payment_method_type": "visa",
            "payment_description": "",
            "operation_created_at": "2024-04-04T08:28:47+00:00",
            "provider_date": "2024-04-04 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 default set of data retrieved for each operation, 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, operation_status, and customer_email.

// Body of the request:
{
    "project_id":[
        0,
        11
    ],
    "interval": {
        "from":"2024-04-04 00:00:00",
        "to":"2024-04-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 an operation
    {
        "operation_id": "12347892",
        "operation_type": "sale",
        "operation_status": "success",
        "sum_initial": {
            "amount": 1000,
            "currency": "USD"
        },
        "customer_email": "astronaut@earth.station"
    },
    // information about other operations ...
    ],
    "signature": "sdkf45rt73jncpEB75HTS=="
}

Requests to retrieve information about all 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 Dashboard user account), and signature (details). 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": "2024-11-22T13:13:04+00:00",
      "operation_type": "refund",
      "operation_id": "2747253065470",
      "amount": 221,
      "currency": "USD",
      "operation_created_at": "2024-11-22T13:13:04+00:00",
      "rrn": "803817399309",
      "payment_provider_code": "0",
      "payment_provider_message": "Success"
    },
    {
      "arn": "",
      "operation_completed_at": "201924-11-22T13:09:03+00:00",
      "operation_type": "capture",
      "operation_id": "2747253065469",
      "amount": 1621,
      "currency": "USD",
      "operation_created_at": "2024-11-22T13:09:03+00:00",
      "rrn": "000000248370",
      "payment_provider_code": "0",
      "payment_provider_message": "Success"
    },
    {
      "arn": "",
      "operation_completed_at": "2024-11-22T13:06:40+00:00",
      "operation_type": "auth",
      "operation_id": "2747253065468",
      "amount": 200,
      "currency": "USD",
      "operation_created_at": "2024-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.

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

• token—a token associated with the specific Dashboard user account that has permissions to access all required projects.
• signature—a request signature generated after all required parameters have been specified (details).
• 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": "2024-11-14 12:00:00",
      "to": "2024-11-14 13:00:00"
    },
  "tz":"Asia/Singapore"
  }
}

// Response body

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