Retrieving data
Overview
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/operations/get-by-payment
—to retrieve information about operations initiated within a specific payment
The general procedure of sending requests to any of these endpoints is the same as described in previous sections. This section covers special aspects of using these requests and complements the description of data structures in the interface specification.
Retrieving balance data
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>"
).
Figure: Example of the request to retrieve balance information and the corresponding response
// Request body
{
"token":"ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
"signature":"dQcIbv94Z0nPTYX9glSCi...jqInXqYrY9bzkfcBGQ=="
}
// Response body
{
"balance": [
{
"name": "Project_Cosmo1_balance_RUB",
"RUB": "1010750"
},
{
"name": "Project_Cosmo1_balance_USD",
"SGD": "310099"
},
{
"name": "Project_Cosmo1_balance_EUR",
"EUR": "113128"
}
],
"signature": "3XOq69...OKvPLwQQrRtwxFy5gTz1ggQkoMK9tw5w=="
}
Retrieving chargeback data
Requests to retrieve chargeback information filtered by specified conditions should be sent to the /chargeback/list endpoint.
When sending such requests, consider the following:
- These requests must contain parameters
token
(a token associated with the specific user account with theRisks
orMerchant Admin
role and with the access rights to certain projects of the merchant) andsignature
. -
To filter information about chargebacks by different parameters, use the
filter
object.In the
filter
object, any date range must be an object defined byfrom
andto
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 thefilter
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 platformrespond_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 ecommpaychargeback_id
—chargeback ID provided by ecommpaychargeback_stage
—chargeback stage (Chargeback
,Representment
,Pre-Arbitration attempt
,Pre-Arbitration response
, orArbitration
; details)arn
—acquirer reference number used for clearingcard
—card number used by the customer to make the disputed paymentcard_type
—the code of the payment system (visa
for Visa andmc
for Mastercard);reason_code
—numerical chargeback reason code provided by the payment systemoperation_id
—ID of the disputed operation provided by ecommpaystatus
—current status of the chargeback
- To restrict the number of chargebacks the information about which is returned in a single response, use the
pagination
object with two parameters:limit
andoffset
. Thelimit
parameter is used to set the number of the returned operations in the response (more than 1). Theoffset parameter
is used to retrieve the subset of chargebacks beginning with the number that follows theoffset
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 forlimit
and 0 foroffset.
Responses to such requests contain chargeback data with the consideration of the conditions determined in the request.
Figure: Example of the request to retrieve chargeback data and the corresponding response
// 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==" }
Retrieving single chargeback data
A request to retrieve single chargeback information should be sent to the /chargeback/get endpoint.
When sending such requests, consider the following:
- The request must contain parameters
token
(a token associated with the specific user account with theRisks
orMerchant Admin
role and with the access rights to certain projects of the merchant) andsignature
. - The request must contain one of the following identifiers in the
filter
object:chargeback_id
—chargeback ID provided by ecommpayarn
—acquirer reference number used for clearingoperation_id
—operation ID provided by ecommpay
The response to such request contains information about the required chargeback.
Figure: Example of the request to retrieve single chargeback data and the corresponding response
// 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==" }
Retrieving fraudulent operations data
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:
- The request must contain parameters
token
(a token associated with the specific user account with theRisks
orMerchant Admin
role and with the access rights to certain projects of the merchant) andsignature
. - 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"]
. - To restrict the number of operations the information about which is returned in a single response, use the
pagination
object with two parameters:limit
andoffset
. Thelimit
parameter is used to set the number of the returned operations in the response (more than 1). Theoffset parameter
is used to retrieve the subset of operations beginning with the number that follows theoffset
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 forlimit
and 0 foroffset
.
Responses to such requests contain operation data filtered by the conditions determined in the request.
Figure: Example of the request to retrieve data and the corresponding response
// 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=="
}
Retrieving operation data
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:
- 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, inYYYY-MM-DD hh:mm:ss
formatto
—end date and time of the interval, inYYYY-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 accountsignature
—a request signature generated after all required parameters have been specified.
- 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 theproject_id
parameter (separated with a comma and a space: for example,4, 12
). - 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 theinterval
object and the format of the date and time parameters in the response—for example,operation_created_at
andoperation_completed_at
. In thetz
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
). -
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 between0
and1000
. By default, it is set to1000
, 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 bothlimit
andoffset
parameters are passed in the request, then the number of the operations included in the first response equals the value of theoffset
parameter, and the remaining number of operations returned in the second response does not exceed the value of thelimit
parameter.For example, if you need to retrieve operation data on
1125
operations, then you can specify the following values for thelimit
andoffset
parameter in the requests:"limit": "1000"
and"offset": "0"
in the first one,"limit": "125"
and"offset": "1000"
in the second one. - To restrict the number of operations returned in a single response, use the
limit
parameter with a value between0
and1000
. If you need information about more than one thousand operations, send several requests with theoffset
parameter specified in each. This parameter determines the offset value for selecting operations. -
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 thefields
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. - 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 theoperations
object included in the format description of the response to the request sent to the /operations/get endpoint. -
To retrieve operation data by certain operation types and/or statuses, use the
operation_type
andoperation_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 theoperation_type
andoperation_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
andoperation_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). -
To filter operation data by customer IDs and/or customer emails, use the
customer_id
array andcustomer_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.
Figure: Example of data passed in the requests to retrieve operation data and the response to one of them
// 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": "RUB"
},
"sum_converted": {
"amount": 1000,
"currency": "RUB"
},
"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": "RUB"
},
"sum_converted": {
"amount": 1000,
"currency": "RUB"
},
"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
.
Figure: Example of data passed in the requests to retrieve customised set of parameters and the response
// 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=="
}
Retrieving data on operations initiated within a specific payment
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.
Figure: Example of the request to retrieve data on operations within a specific payment and the response to it
// 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": "RUB",
"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": "RUB",
"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": 2000,
"currency": "RUB",
"operation_created_at": "2019-11-22T13:06:38+00:00",
"rrn": "000047769105",
"payment_provider_code": "0",
"payment_provider_message": "Success"
}
],
"signature": "hsUpqn7QPDxNLNH/ZulaK6ICiH7bABSdjLPkQXkMjQ7tqoB8TCJR1Oh2xyiA8y1WihDJ4ljz/Hv7NkQFujSnvw=="
}