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

Общая информация

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

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

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

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

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

В этих запросах должны указываться параметры token (токен учётной записи) и 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 (токен учётной записи с ролью 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": "2022-01-01",
            "to": "2022-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": "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=="
}

Контроль отдельных опротестований

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

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

  1. В каждом запросе должны указываться параметры token (токен учётной записи с ролью 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": "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=="
}

Контроль мошеннических операций

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

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

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

    В этом объекте любой период должен задаваться через массив строк с границами временного интервала, например "purchase_date": [ "2021-12-31 00:00:00", "2022-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": [
      "2022-01-01 00:00:00",
      "2022-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": "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=="
}

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

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

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

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

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

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

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

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

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

  9. Для фильтрации данных об операциях с учётом идентификаторов и (или) адресов электронной почты пользователей используются параметры 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": "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": "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": "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": "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, 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": "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 (токен учётной записи) и 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": "USD",
      "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": "USD",
      "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": 200,
      "currency": "USD",
      "operation_created_at": "2019-11-22T13:06:38+00:00",
      "rrn": "000047769105",
      "payment_provider_code": "0",
      "payment_provider_message": "Success"
    }
  ],
  "signature": "hsUpqn7QPDxNLNH/ZulaK6ICiH7bABSdjLPkQXkMjQ7tqoB8TCJR1Oh2xyiA8y1WihDJ4ljz/Hv7NkQFujSnvw=="
}

Контроль информации о курсах конвертации валют

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

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

Прим.: Чтобы получать фактическую информацию о курсах конвертации, применённых для конкретных списаний и зачислений (и актуальных для итогового анализа и сверок), можно использовать регулярные операционные отчёты от ecommpay и информацию об операциях, выгружаемую через запросы к конечным точкам группы operations.

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

  • token — токен учётной записи 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": "2023-11-14 12:00:00",
      "to": "2023-11-14 13:00:00"
    },
  "tz":"Asia/Singapore"
  }
}

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

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