Получение данных

В структуре Data API используются разные конечные точки для получения разной информации:

• /balance/get— для получения информации о балансах по проектам мерчанта (в настоящее время поддерживается получение информации только о балансах типа OUT);
• /chargeback/list — для получения информации об опротестованиях, соответствующих заданным условиям;
• /chargeback/get — для получения информации по конкретному опротестованию;
• /fraud/list — для получения информации об операциях, признанных мошенническими;
• /financial-reporting/operations — для получения информации о финансовых результатах по операциям за заданный период (включая информацию о начисленных комиссиях);
• /operations/get — для получения информации о выполнении операций за заданный период;
• /operations/get-by-payment — для получения информации об операциях конкретного платежа;
• /currency-rates/get — для получения ознакомительной информации о курсах конвертации, применяемых к списаниям и зачислениям.

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

Для получения информации о балансах по проектам мерчанта следует отправлять запросы к конечной точке /balance/get.

В этих запросах должны указываться параметры token (токен учётной записи Dashboard) и signature (подпись; подробнее). В ответах на такие запросы содержатся сведения о текущем состоянии балансов типа OUT.

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

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

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

Для получения информации об опротестованиях (chargebacks), которые относятся к проектам мерчанта и соответствуют заданным условиям, следует отправлять запросы к конечной точке /chargeback/list.

В работе с этими запросами необходимо учитывать следующее:

1. В каждом запросе должны указываться параметры token (токен учётной записи Dashboard с ролью Risks или Merchant admin и правами доступа ко всем целевым проектам) и signature (подпись; подробнее).

2. Для фильтрации данных об опротестованиях могут использоваться любые из параметров в объекте filter.

   В этом объекте каждый из периодов задаётся как объект с двумя параметрами строкового типа from (начало) и to (окончание). Остальные параметры могут содержать как одно, так и несколько значений, заданных в виде массива или строки с разделением через запятую с пробелом. Исключением является параметр provider_id, который может быть задан только в виде массива. Параметры фильтрации можно указывать в произвольном порядке. Если они не указываются вовсе, в ответе от платёжной платформы отправляются данные обо всех опротестованиях по проектам, к которым есть доступ у используемой учётной записи.

   В объекте filter могут указываться следующие объекты и параметры:

   • report_date — период, в котором информация об опротестовании впервые поступила в платформу (формат каждой границы периода — ГГГГ-ММ-ДД);
   • respond_by — период, к которому относится последний день срока предоставления ответа по опротестованию (формат каждой границы периода — ГГГГ-ММ-ДД чч:мм:сс с возможностью не указывать время);
   • chb_completed_at — период, в котором опротестованию присвоен итоговый статус (формат каждой границы периода — ГГГГ-ММ-ДД чч:мм:сс с возможностью не указывать время);
   • project_id — идентификатор проекта;
   • chargeback_id — идентификатор опротестования, полученный от ecommpay;
   • chargeback_stage — этап работы с опротестованием (Chargeback, Representment, Pre-Arbitration attempt, Pre-Arbitration response и Arbitration; подробнее об этапах);
   • arn — acquirer reference number (идентификатор операции, присвоенный эквайером);
   • card — номер платёжной карты, использованной при проведении платежа;
   • card_type — код платёжной системы (visa для Visa и mc для Mastercard);
   • reason_code — числовой код причины опротестования, полученный от платёжной системы;
   • operation_id — идентификатор оспариваемой операции;
   • status — статус опротестования.
3. Для ограничения количества записей с информацией об опротестованиях, возвращаемых в одном ответе, можно использовать объект pagination с двумя параметрами: limit — максимальное количество возвращаемых записей (не меньше 1) и offset — величина сдвига для отбора записей (с отсчётом с 0). Например, если необходимо получить информацию о 5 опротестованиях, пропустив первые 20, то в запросе можно указать "limit": 5 и "offset": 20. При отсутствии этих параметров используются значения по умолчанию: limit — 20, offset — 0.

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

// Тело запроса
{
    "token": "ZOyTL5shYsdhpxdQdfdfJYmGV7Kv",
    "filter": {
        "report_date": {
            "from": "2024-01-01",
            "to": "2024-02-01"
        },
        "status": [
            "WON",
            "PARTIALLY WON"
        ]
    },
    "signature": "DNqOZOCxNlXu3bENrDPuEE8fSJLWDNM/...UqhiEUoC5VcNFw=="
}

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

Для получения информации об отдельных опротестованиях (chargebacks) следует использовать запросы к конечной точке /chargeback/get.

В работе с этими запросами необходимо учитывать следующее:

1. В каждом запросе должны указываться параметры token (токен учётной записи Dashboard с ролью Risks или Merchant admin и правами доступа ко всем целевым проектам) и signature (подпись; подробнее).
2. Дополнительно должен указываться по крайней мере один из следующих идентификаторов в объекте filter:
   • chargeback_id — идентификатор опротестования, полученный от ecommpay;
   • arn — идентификатор операции, присвоенный эквайером (acquirer reference number);
   • operation_id — идентификатор операции в платёжной платформе.

   Если в запросе не указан ни один из этих идентификаторов или указаны противоречащие друг другу, то в ответ выдаётся ошибка.

В ответе на корректный запрос содержатся данные о конкретном опротестовании.

// Тело запроса
{
  "token": "ZOyTL5shYsdhpxdQdfdfJYmGV7Kv",
  "filter": {
        "operation_id": 87980010093051
    },
  "signature": "VoOJxpMge0uBN22gZxf3BhE+5wlCaU...y+KM1lQ=="
}

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

Для получения информации об операциях, признанных мошенническими на стороне платёжных систем, следует отправлять запросы к конечной точке /fraud/list.

Стоит учитывать, что с помощью таких запросов нельзя получать данные об операциях, признанными подозрительными на стороне ecommpay, а в работе с этими запросами необходимо учитывать следующее:

1. В каждом запросе должны указываться параметры token (токен учётной записи Dashboard с ролью Risks или Merchant admin и правами доступа ко всем целевым проектам) и signature (подпись; подробнее).
2. Для фильтрации данных об операциях могут использоваться любые из параметров в объекте filter:
   • received_on — период, в котором операция признана мошеннической на стороне платёжной системы;
   • purchase_date — период, в котором операции присвоен итоговый статус;
   • fraud_report_date — период, в котором эмитент был уведомлён о признании операции мошеннической;
   • issuer_country — код страны эмитента, выпустившего карту (массив из одного или нескольких кодов в формате ISO 3166-1 alpha-2).

   В этом объекте любой период должен задаваться через массив строк с границами временного интервала, например "purchase_date": [ "2023-12-31 00:00:00", "2024-01-07 23:59:59" ].

3. Для ограничения количества записей с информацией об операциях, возвращаемых в одном ответе, можно использовать объект pagination с двумя параметрами: limit — максимальное количество возвращаемых записей (не меньше 1) и offset — величина сдвига для отбора записей (с отсчётом с 0). Например, если необходимо получить информацию о 5 операциях, пропустив первые 20, то в запросе можно указать "limit": 5 и "offset": 20. При отсутствии этих параметров используются значения по умолчанию: limit — 20, offset — 0.

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

// Тело запроса
{
  "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
  }
}

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

Для получения информации о финансовых результатах по операциям за заданный период (включая информацию о начисленных комиссиях) следует отправлять запросы к конечной точке /financial-reporting/operations. Эта информация может дополнять информацию о выполнении операций (подробнее) и использоваться для итогового анализа и сверок.

В работе с запросами на получение информации о финансовых результатах по операциям необходимо учитывать следующее:

В работе с этими запросами необходимо учитывать следующее:

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

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

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

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

5. Для ограничения количества записей, возвращаемых в одном ответе, используется параметр limit со значением в диапазоне 0—1000. А при необходимости получить информацию более чем о тысяче операций следует отправлять группу запросов, используя в каждом из них параметр offset, который определяет величину сдвига для отбора операций.

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

// Тело запроса на получение данных о 1000 операциях (с отсчётом от 0) 
{
  "project_id": [11],
  "operation_completed_at": {
    "from": "2024-09-01 00:00:00",
    "to": "2024-09-30 23:59:59"
  },
  "tz": "Indian/Mauritius",
  "limit": 1000,
  "offset": 0,
  "token": "ZOyTL5shY8ddhpxdQyplRPJYmGV7Kv",
  "signature": "YsrkgdBr5peXJgJ...glVmsd0f=="
}

// Тело ответа на запрос
 
{
  "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"
    },
    // сведения об остальных операциях...
  ],  
  "signature": "sncpEB75H...3jTS=="
}

Для получения информации о выполнении операций за заданный период следует отправлять запросы к конечной точке /operations/get. Эту информацию можно использовать в ознакомительных целях и для развёрнутого анализа выполнения операций, в то время как для итогового анализа и сверок можно использовать информацию о финансовых результатах по операциям (с учётом начисленных комиссий; подробнее).

В работе с запросами на получение информации о выполнении операций необходимо учитывать следующее:

В работе с этими запросами необходимо учитывать следующее:

1. В каждом запросе должны использоваться следующие объекты и параметры:
   • token — токен учётной записи Dashboard;
   • signature — подпись запроса, составленная после указания целевых параметров (подробнее);
   • interval — объект с информацией о границах временно́го интервала, к которому относятся целевые операции (с учётом последних действий и обновлений информации по ним):
     • from — дата и время начала интервала, в формате ГГГГ-ММ-ДД чч:мм:сс;
     • to — дата и время окончания интервала, в формате ГГГГ-ММ-ДД чч:мм:сс.
     Прим.: Если от имени одной учётной записи Dashboard в течение 10 секунд в платформу поступает более одного запроса на информацию за период, превышающий 180 дней, то эти запросы обрабатываются поэтапно, с тайм-аутом в 10 секунд.
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. Для ограничения количества записей, возвращаемых в одном ответе, используется параметр limit со значением в диапазоне в диапазоне 0—1000. При необходимости получить информацию более чем о тысяче операций следует отправлять группу запросов, используя в каждом из них параметр offset, который определяет величину сдвига для отбора операций.

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

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

7. Для указания состава возвращаемых данных об операциях используется массив fields. Полный перечень допустимых параметров представлен в спецификации Data API — в виде параметров объекта operations в описании формата ответа на запрос к конечной точке /operations/get.

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

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

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

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

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

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

// Тело запроса на получение данных о следующих 125 операциях (с отсчётом от 1000)
{
  "project_id":[
    0,
    11
  ],
  "interval": {
    "from":"2024-04-04 00:00:00",
    "to":"2024-04-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": "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"
        },

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

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

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

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

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

Для получения информации обо всех операциях по конкретному платежу следует использовать запрос к конечной точке /operations/get-by-payment.

В этом запросе должны указываться параметры payment_id (идентификатор целевого платежа), token (токен учётной записи Dashboard) и signature (подпись; подробнее). В ответе на такой запрос содержатся сведения об операциях целевого платежа.

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

// Тело ответа
{
  "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": "2024-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/ZulaK6ICiH7b...y1WihDJ4ljz/Hv7NkQFujSnvw=="
}

Для получения ориентировочной информации о курсах конвертации валют, применяемых в платформе к операционным и неоперационным списаниям и зачислениям, можно использовать запросы к конечной точке /currency-rates/get.

В ответе на каждый запрос к этой точке приводятся „опорные“ значения курсов продажи и покупки заданной валюты по отношению к доллару США на начало каждого часа в рамках заданного периода. Кроме того, в отдельных случаях, в частности для болгарского лева (BGN), дополнительно приводятся значения курса по отношению к евро (EUR).

В каждом запросе к конечной точке /currency-rates/get должны использоваться следующие объекты и параметры:

• token — токен учётной записи Dashboard c правами доступа ко всем целевым проектам.
• signature — подпись запроса, составленная после указания целевых параметров (подробнее).
• filter — объект с данными для фильтрации курсов конвертации целевой валюты:
  • merchant — внутренний идентификатор мерчанта в платформе, предоставляемый специалистами технической поддержки ecommpay по отдельным запросам и указываемый в виде числа (например, 97).
  • currency — код целевой валюты в формате ISO-4217 alpha-3 (подробнее).
  • interval — объект с указателями границ временно́го интервала:
    • from — дата и время начала интервала, в формате ГГГГ-ММ-ДД чч:мм:сс;
    • to — дата и время окончания интервала, в формате ГГГГ-ММ-ДД чч:мм:сс.
    Прим.: В случаях, когда заданный период составляет менее часа (вплоть до совпадения времени начала и окончания периода), приводятся курсы, актуальные для параметра from. Если указывается некорректный период (например, из будущего времени), то в ответе на такой запрос данные о курсах отсутствуют.
• tz — указатель часового пояса, задаваемый через время смещения в формате UTC (например, +10:30) или через название пояса в соответствии с базой данных IANA Time Zone Database (например, Asia/Singapore).

// Тело запроса
{
  "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"
  }
}

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

{
    "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=="
}