Получение информации о балансах и платежах

Общие сведения

В структуре Data API используются разные конечные точки для получения разных видов данных:

  • /v1/balance/get — для получения данных о балансах по проектам мерчанта (в настоящее время поддерживается получение информации только о балансах типа OUT);
  • /v1/operations/get — для получения данных об операциях за заданный период;
  • /v1/operations/get-by-payment — для получения данных об операциях конкретного платежа.

Общий порядок работы с каждой из этих конечных точек соответствует описанному в предыдущих разделах. В этом разделе представлена информация об особенностях запросов к этим конечным точкам, дополняющая описания структур данных в спецификации интерфейса.

Контроль балансов

Для получения данных о балансах по проектам мерчанта следует отправлять запросы в конечную точку /v1/balance/get. В этих запросах должны указываться параметры token (токен учетной записи) и signature (подпись). В ответах на такие запросы содержатся сведения о текущем состоянии балансов типа OUT.

Сведения о каждом балансе это наименование баланса и доступная сумма в валюте этого баланса, причем валюта указывается в названии параметра, а сумма — в его значения, например "<валюта>": "<сумма>".

Рис.: Пример данных из запроса на получение данных о балансах и ответа на этот запрос

// Тело запроса
{
  "token": "ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
  "signature": "dQcIbv94Z0nPTYX9glSCi...jqInXqYrY9bzkfcBGQ=="
}

// Тело ответа
{
    "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=="
}

Общий контроль операций

Для получения данных об операциях за заданный период по проектам мерчанта следует отправлять запросы к конечной точке /v1/operations/get. При этом необходимо учитывать следующее:

  1. В каждом запросе должны использоваться следующие объекты и параметры:
    • interval — объект с информацией о границах временно́го интервала, к которому относятся последние действия (и соответствующие обновления информации) по целевым операциям:
      • from — дата и время начала интервала, в формате ГГГГ-ММ-ДД чч:мм:сс;
      • to — дата и время окончания интервала, в формате ГГГГ-ММ-ДД чч:мм:сс;
    • token — токен учетной записи;
    • signature — подпись запроса, составленная после указания целевых параметров.
  2. Для фильтрации операций по их отношению к проектам используется параметр project_id, а также учитывается наличие прав доступа к проектам через токен, указанный в запросе. По умолчанию, если в запросе не указан этот параметр, в ответе от платежной платформы отправляются данные об операциях по всем проектам, к которым есть права доступа через используемый токен. При необходимости получить данные по конкретным проектам (одному или нескольким), в параметре project_id следует указать идентификаторы этих проектов (через запятую с пробелом, если необходимо указать несколько идентификаторов; например, 4, 12).
  3. Для использования часового пояса, отличного от заданного по умолчанию UTC +00:00, используется параметр tz. Выбор часового пояса с помощью этого параметра влияет на то, какие операции попадают в заданный интервал времени в объекте interval, и на значения параметров в ответе, связанных с датой и временем — например, operation_created_at и operation_completed_at. Часовой пояс в параметре tz указывается через время смещения в формате UTC (например, +10:30) или через название в соответствии с базой данных часовых поясов IANA Time Zone Database (например, Asia/Singapore).

  4. Для ограничения количества записей с информацией об операциях, возвращаемых в одном ответе, используется параметр limit. Этот параметр может принимать значения в диапазоне 0–1000 и по умолчанию равен 1000, при этом количество записей, возвращаемых в ответе, может быть меньше заданного значения.

    При необходимости получить информацию более чем о тысяче операций, следует отправлять несколько запросов и в каждом из них использовать параметр offset. Этот параметр определяет величину сдвига для отбора операций. Когда в запросе указываются оба параметра — и limit, и offset, то сначала операции пропускаются в количестве, заданном значением offset, а затем записи с информацией о следующих операциях возвращаются в ответе в количестве, не превышающем значения limit.

    Например, если необходимо получить информацию о 1125 операциях, то в первом запросе можно указать "limit": 1000 и "offset": 0, а во втором — "limit": 125 и "offset": 1000.

  5. Для фильтрации данных об операциях по различным параметрам используется массив fields. По умолчанию, если в запросе не указан этот массив, в ответе от платежной платформы отправляется типовой набор данных для каждой операции. Если же необходимо получить данные по конкретным параметрам (одному или нескольким), в качестве элементов массива fields следует указать названия этих параметров.

    Параметры указываются в массиве через запятую с пробелом (если необходимо указать несколько названий), при этом их можно указывать в произвольном порядке, но в ответах используется фиксированный порядок данных. Полный перечень параметров представлен в спецификации Data API — в виде параметров объекта operations в описании формата ответа на запрос к конечной точке /v1/operations/get. В этом описании атрибуты указаны в порядке, который используется по умолчанию, и отмечены как обязательные.

  6. Для получения данных об операциях по конкретным типам и (или) статусам используются массивы operation_type и operation_status. По умолчанию, если в запросе не указаны эти массивы, в ответе отправляются данные об операциях всех допустимых типов и статусов. В качестве элементов массивов operation_type и operation_status следует указывать названия конкретных типов и статусов операций соответственно, через запятую с пробелом, если необходимо указать несколько названий. Полный перечень типов и статусов операций представлен в разделе Типы платежей, операции и платежи.

    Параметры operation_type и operation_status могут иметь тип массив строк (если необходимо указать одно или несколько значений) или строковый тип (если необходимо указать одно значение).

  7. Для фильтрации данных об операциях с учетом идентификаторов и (или) адресов электронной почты пользователей используются параметры customer_id (массив строк) и customer_email (строка). По умолчанию, если в запросе не указаны эти параметры, в ответе отправляются данные об операциях с любыми идентификаторами и адресами электронной почты пользователей.

    Параметр customer_id может иметь тип массив строк (если необходимо указать одно или несколько значений) или строковый тип (если необходимо указать одно значение).

В ответе на каждый из таких запросов содержатся данные об операциях за указанный период с учетом условий, заданных в запросе.

Если достаточно параметров, используемых по умолчанию, можно не указывать в запросах массив fields.

Рис.: Пример данных из запросов на получение данных об операциях и ответа на один из таких запросов

// Тело запроса на получение данных о 1000 операциях (с отсчетом от 0) 
{
  "project_id": [
    0,
    11
  ],
  "interval": {
    "from": "2020-08-01 00:00:00",
    "to": "2020-08-28 23:59:59"
  },
  "limit": 1000,
  "offset": 0,
  "token": "ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
  "signature": "yPu0wYr2BoV5...MzQtRkvdC0y=="
}

// Тело запроса на получение данных о следующих 125 операциях (с отсчетом от 1000)
{
  "project_id": [
    0,
    11
  ],
  "interval": {
    "from": "2020-08-01 00:00:00",
    "to": "2020-08-28 23:59:59"
  },
  "limit": 125,
  "offset": 1000
  "token": "ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
  "signature": "sd0fr5YsdBVmJ...grkglpeXJg=="
}

// Тело ответа на первый запрос
{
    "operations": [
        // сведения об операции
        { 
            "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"
        },

        // сведения о следующей операции
        { 
            "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"
        },
        // сведения об остальных операциях
        ...
    ],
    "signature": "k4iXC845FvT+HdWdxMkXAV8dS0AH5BGIw=="
}

Если нужны нетиповые параметры по операциям, можно задавать целевые параметры через массив fields, а если еще и необходимо применить фильтрацию операций, то можно задавать критерии фильтрации через различные параметры, например operation_type, opeartion_status и customer_email.

Рис.: Пример данных из запроса на получение нетипового набора данных об операциях и ответа

// Тело запроса на получение данных:
{
    "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=="
}

// Тело ответа:

{
    "operations": [
    // сведения об операции
    {
        "operation_id": "12347892",
        "operation_type": "sale",
        "operation_status": "success",
        "sum_initial": {
            "amount": 1000,
            "currency": "USD"
        },
        "customer_email": "johndoe@example.com"
    },
    // сведения об остальных операциях ...
    ],
    "signature": "sf45rt73jn...B75HTS=="
}

Контроль операций по отдельным платежам

Для получения данных обо всех операциях конкретного платежа следует использовать запрос к конечной точке /v1/operations/get-by-payment. В этом запросе должны указываться параметры payment_id (идентификатор целевого платежа), token (токен учетной записи) и signature (подпись). В ответе на такой запрос содержатся сведения об операциях целевого платежа.

Рис.: Пример данных из запроса информации об операциях конкретного платежа и ответа на этот запрос

// Тело запроса
{
  "payment_id": "PID_25467851461-2147",
  "token": "VmJQhaXILAnZWTKmqwSd3j",
  "signature": "JM+YWmTL7uGn26IgZWTKmqwSd3jJM+YWmTL7uGn26IglUOMzQtRkvdC0yaq030+eNXVtJjjtgrkglpeXJg=="
}

// Тело ответа
{
  "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=="
}