Retrieving balance and historical payment data

Overview

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

  • /v1/balance/get—to retrieve balance information (currently available only for OUT balances)
  • /v1/operations/get—to retrieve operation information for a specified time period
  • /v1/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.

Monitoring balances

Requests to retrieve balance information on the merchant's projects should be sent to the /v1/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=="
}

Monitoring general operation data

Requests to retrieve operation information for a specified time period on the merchant's projects should be sent to the /v1/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
    • 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 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 /v1/operations/get endpoint. In this description, the parameters are listed in the default order and marked as required.

  6. 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. For the comprehensive list of operation types and statuses, see Payment types, operations and payments.

    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).

  7. 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 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": "424242******4242",
            "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"
        },

        // information about another operation
        { 
            "project_id": "11",
            "operation_id": "6435212162442",
            "payment_id": "EP06c1-b285",
            "operation_type": "sale",
            "operation_status": "success",
            "account_number": "424242******4242",
            "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"
        },
        // information about the rest of the operations
        ...
    ],
    "signature": "k4iXC845FvT+HdWdxMkXAV8dS0AH5BGIw=="
}

If you need to customize 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 customized set of parameters and the response

// Request body
{
    "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": "johndoe@example.com",
    "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": [
    // the operation details
    {
        "operation_id": "12347892",
        "operation_type": "sale",
        "operation_status": "success",
        "sum_initial": {
            "amount": 1000,
            "currency": "USD"
        },
        "customer_email": "johndoe@example.com"
    },
    // other operations details...
    ],
    "signature": "sf45rt73jncpEB75HTS...fdh=="
}

Monitoring operations initiated within a specific payment

Requests to retrieve information about operations initiated within a specific payment should be sent to the /v1/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+YWmTL7uGn26Ig...asd=="
}

// 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"
    },
    {
      "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"
    },
    {
      "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"
    }
  ],
  "signature": "hsUpqn7QPDxNLNH/ZulaK6ICiH7bABSdjLPkQXkMjQ7tqoB8TCJR1Oh2xyiA8y1WihDJ4ljz/Hv7NkQFujSnvw=="
}