# Передача дополнительных сведений об оплатах для их учёта на стороне веб-сервиса {#ru_pp_additional_data}

статья о возможности фиксировать при работе через Payment Page сопутствующую информацию о проводимых оплатах для её внутреннего использования в работе мерчантов

**На уровень выше:**[Вспомогательные процедуры и дополнительные возможности](ru_PP_Additional.md)

## Введение {#ru_pp_additional_data_overview}

В некоторых случаях при проведении платежей может быть актуально передаватьне только обязательные и рекомендуемые со стороны провайдера параметры, но и те сведения, которые могут быть полезны в дальнейшем на стороне мерчанта\(с привязкой к конкретным платежам и их статусам\). Для таких ситуаций в структуре Payment Page API предусмотрены параметры, позволяющие передавать различные сведения в запросах и получать эти сведения вместе с другой информацией в составе итоговых оповещений.

**Прим.:** При работе с Gate API можно использовать аналогичные [возможности](ru_gate_additional_data.md#).

## Передача сведений о бронировании товаров и услуг {#ru_pp_booking_data}

### Общая информация {#section_hxj_4jg_g1c .section}

С помощью параметра `booking_info` можно фиксировать сведения о бронировании, связанном с оплатой, и получать эти сведения в оповещениях от платёжной платформы. Эта возможность может применяться достаточно широко \(например, для указания сведений о бронировании билетов на концерт\) и гибко, без ограничений на категорию мерчанта \(согласно коду [Merchant Category Code, MCC](ru_glossary.md#)\). При наличии вопросов о работе с этой возможностью можно обращаться к курирующему менеджеру Ecommpay.

Параметр `booking_info` может использоваться практически для всех целевых действий с прямым использованием платёжных карти с использованием методов Apple Pay, Click to Pay и Google Pay: в частности, для проведения оплат, блокировки средств, регистрации нерегулярных повторяемых оплат и проверки платёжных инструментов.

**Внимание:** В целях повышения качества обработки платежей и соблюдения отраслевых стандартов с 15 января 2026 года для определённых видов бизнеса обязательна передача параметра `booking_info` с информацией о датах начала и окончания бронируемой услуги \(в параметрах `start_date` и `end_date`\) для каждой инициируемой [карточной оплаты](ru_pm_cardpayments.md). Это относится к мерчантам с кодами категорий 3000–3999, 4411, 4511, 4722, 5962, 6513, 7011, 7012, 7512, 7519 и 7922.

### Пример использования {#section_x3n_yjg_g1c .section}

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

-   сбор и обработку информации о бронированиях билетов на фестивали;
-   оперативный доступ своих сотрудников к актуальной информации такого рода по каждому пользователю.

Для этого настраивается следующая схема работы:

1.  В каждом запросе на открытие Payment Page со стороны веб-сервиса мерчанта передаются сведения о бронировании в параметре `booking_info`. В значении этого параметра указывается строка, полученная в результате кодирования JSON-объекта алгоритмом Base64.

    Исходный JSON-объект может включать в себя следующую информацию.

    -   Массив `bookers` с информацией о лицах, для которых бронируется услуга. Каждый элемент такого массива содержит:
        -   `first_name` — имя получателя услуги, указанное при бронировании;
        -   `last_name` — фамилия получателя услуги, указанная при бронировании;
        -   `email`— адрес электронной почты, указанный при бронировании.
    -   Массив `items` с информацией об отдельных услугах, которые входят в состав бронирования. Каждый элемент такого массива содержит:
        -   `description` — описание отдельной услуги в рамках бронирования;
        -   `start_date` — дата начала действия отдельной услуги;
        -   `end_date` — дата окончания действия отдельной услуги.
    -   А также следующие параметры:

        -   `start_date` — дата начала действия забронированной услуги;
        -   `end_date` — дата окончания действия забронированной услуги;
        -   `description` — произвольное описание бронирования;
        -   `total` — итоговая стоимость бронирования;
        -   `pax` — количество лиц, для которых бронируется услуга;
        -   `reference` — указатель забронированной услуги, в качестве которого могут выступать URL, название или код услуги в сервисе мерчанта;
        -   `id` — идентификатор бронирования, уникальный в рамках сервиса мерчанта.
        **Прим.:** Стоит учитывать, что в параметрах `start_date` и `end_date` исходного JSON-объекта должны передаваться даты начала и окончания забронированной услуги в целом, а в параметрах `start_date` и `end_date` массива `items` — даты начала и окончания отдельных её составляющих.

        **Внимание:** В параметрах `total` и `pax` следует передавать численное значение выше `0`.

2.  По результатам выполнения соответствующей операции информация из параметра `booking_info` передаётся к веб-сервису мерчанта в итоговом оповещениии становится доступной для просмотра в карточке платежа интерфейса Dashboard.
3.  На стороне веб-сервиса обеспечивается необходимая обработка получаемой информации вместе с другой информацией о выполняемых операциях.

### Подключение {#section_b2p_nkg_g1c .section}

Указывать параметр `booking_info` в запросах и получать передаваемые в нём сведения в оповещениях \(при использовании типовой структуры оповещений\) можно без согласований и каких-либо дополнительных действий. Эти возможности доступны по умолчанию.

### Формат данных {#section_pzw_4kg_g1c .section}

Параметр `booking_info` может включаться в запросы на открытие Payment Page в виде строки, полученной в результате кодирования с применением алгоритма Base64 JSON-объекта `booking_info` с необходимыми параметрами бронирования.

|Параметр|Описание| |
|--------|--------|--|
|`bookers`  
 array

|Массив с информацией о лицах, для которых бронируется услуга|1|
|`first_name`  
 string

|Имя получателя услуги, указанное при бронировании|1-11|
|`last_name`  
 string

|Фамилия получателя услуги, указанная при бронировании|1-21|
|`email`  
 string

|Адрес электронной почты, указанный при бронировании|1-31|
|`items`  
 array

|Массив с информацией об отдельных услугах, которые входят в состав бронирования|2|
|`description`  
 string

|Описание отдельной услуги в рамках бронирования|2-12|
|`start_date`  
 string

|Дата начала действия отдельной услуги, в формате `ДД-ММ-ГГГГ`|2-22|
|`end_date`  
 string

|Дата окончания действия отдельной услуги, в формате `ДД-ММ-ГГГГ`|2-32|
|`start_date`  
 string

|Дата начала действия забронированной услуги, в формате `ДД-ММ-ГГГГ`|3|
|`end_date`  
 string

|Дата окончания действия забронированной услуги, в формате `ДД-ММ-ГГГГ`|4|
|`description`  
 string

|Произвольное описание бронирования|5|
|`total`  
 integer

|Итоговая стоимость бронирования. Указываемое значение должно быть выше `0`|6|
|`pax`  
 integer

|Количество лиц, для которых осуществлено бронирование. Указываемое значение должно быть выше `0`|7|
|`reference`  
 string

|Указатель забронированной услуги, в качестве которого могут выступать URL, название или код услуги в сервисе мерчанта|8|
|`id`  
 string

|Идентификатор бронирования, уникальный в рамках сервиса мерчанта|9|

```language-json
"booking_info": {
  "start_date": "12-08-2026",
  "end_date": "14-08-2026",
  "description": "Sideris music festival full pass",
  "total": 200000,
  "pax": 2,
  "bookers": [
     {
        "first_name": "William",
        "last_name": "Herschel",
        "email": "rsfellow@mail.com"
     },
     {
        "first_name": "Caroline",
        "last_name": "Herschel",
        "email": "salariedastronomer@mail.com"
     }
  ],        
  "items":[
     {
        "description": "VIP Arrival",
        "start_date": "12-08-2026",
        "end_date": "12-08-2026"
     },
     {
        "description": "Hotel",
        "start_date": "12-08-2026",
        "end_date": "14-08-2026"
     },
     {
        "description": "Concerts",
        "start_date": "12-08-2026",
        "end_date": "14-08-2026"
     },
     {
        "description": "VIP Departure",
        "start_date": "14-08-2026",
        "end_date": "14-08-2026"
     }
  ],
  "reference": "musicfestlink",
  "id": "83"
}
```

```
ewogICJzdGFydF9kYXRlIjogIjEyLTA4LTIwMjYiLAogICJlbmRfZGF0ZSI6ICIxNC0wOC0yMDI2IiwKICAiZGVzY3JpcHRpb24iOiAiU2lkZXJpcyBtdXNpYyBmZXN0aXZhbCBmdWxsIHBhc3MiLAogICJ0b3RhbCI6IDIwMDAwMCwKICAicGF4IjogMiwKICAiYm9va2VycyI6IFsKICAgICB7CiAgICAgICAgImZpcnN0X25hbWUiOiAiV2lsbGlhbSIsCiAgICAgICAgImxhc3RfbmFtZSI6ICJIZXJzY2hlbCIsCiAgICAgICAgImVtYWlsIjogInJzZmVsbG93QG1haWwuY29tIgogICAgIH0sCiAgICAgewogICAgICAgICJmaXJzdF9uYW1lIjogIkNhcm9saW5lIiwKICAgICAgICAibGFzdF9uYW1lIjogIkhlcnNjaGVsIiwKICAgICAgICAiZW1haWwiOiAic2FsYXJpZWRhc3Ryb25vbWVyQG1haWwuY29tIgogICAgIH0KICBdLCAgICAgICAgCiAgIml0ZW1zIjpbCiAgICAgewogICAgICAgICJkZXNjcmlwdGlvbiI6ICJWSVAgQXJyaXZhbCIsCiAgICAgICAgInN0YXJ0X2RhdGUiOiAiMTItMDgtMjAyNiIsCiAgICAgICAgImVuZF9kYXRlIjogIjEyLTA4LTIwMjYiCiAgICAgfSwKICAgICB7CiAgICAgICAgImRlc2NyaXB0aW9uIjogIkhvdGVsIiwKICAgICAgICAic3RhcnRfZGF0ZSI6ICIxMi0wOC0yMDI2IiwKICAgICAgICAiZW5kX2RhdGUiOiAiMTQtMDgtMjAyNiIKICAgICB9LAogICAgIHsKICAgICAgICAiZGVzY3JpcHRpb24iOiAiQ29uY2VydHMiLAogICAgICAgICJzdGFydF9kYXRlIjogIjEyLTA4LTIwMjYiLAogICAgICAgICJlbmRfZGF0ZSI6ICIxNC0wOC0yMDI2IgogICAgIH0sCiAgICAgewogICAgICAgICJkZXNjcmlwdGlvbiI6ICJWSVAgRGVwYXJ0dXJlIiwKICAgICAgICAic3RhcnRfZGF0ZSI6ICIxNC0wOC0yMDI2IiwKICAgICAgICAiZW5kX2RhdGUiOiAiMTQtMDgtMjAyNiIKICAgICB9CiAgXSwKICAicmVmZXJlbmNlIjogIm11c2ljZmVzdGxpbmsiLAogICJpZCI6ICI4MyIKfQ==
```

```language-json
{
    "payment": {
        "date": "2024-01-24T06:24:45+0000",
        "method": "card",
        "id": "FESTIVAL_PASS_1781",
        "sum": {
            "amount": 0,
            "currency": "EUR"
        },
        "type": "purchase",
        "status": "refunded",
        "description": "FESTIVAL_PASS_1781"
    },
    "project_id": 111738,
    "customer": {
        "id": "musicaficionado_83"
    },
    "account": {
        "number": "551115******1822",
        "token": "7123ba1f24f16a115f3390a9",
        "type": "mastercard",
        "card_holder": "WILLIAM HERSCHEL",
        "expiry_month": "08",
        "expiry_year": "2030"
    },
    "booking info": \{    // Объект с информацией о бронировании
        "start\_date": "12-08-2026",
        "end\_date": "14-08-2026",
        "description": "Sideris music festival full pass",
        "total": 200000,
        "pax": 2,
        "bookers": \[
          \{
            "first\_name": "William",
            "last\_name": "Herschel",
            "email": "rsfellow@mail.com"
          \},
          \{
            "first\_name": "Caroline",
            "last\_name": "Herschel",
            "email": "salariedastronomer@mail.com"
          \}
        \],        
        "items": \[
          \{
            "description": "VIP Arrival",
            "start\_date": "12-08-2026",
            "end\_date": "12-08-2026"
          \},
          \{
            "description": "Hotel",
            "start\_date": "12-08-2026",
            "end\_date": "14-08-2026"
          \},
          \{
            "description": "Concerts",
            "start\_date": "12-08-2026",
            "end\_date": "14-08-2026"
          \},
          \{
            "description": "VIP Departure",
            "start\_date": "14-08-2026",
            "end\_date": "14-08-2026"
          \}
        \],
        "reference": "musicfestlink",
        "id": "83"
    \},
    "operation": {
        "provider": {
            "payment_id": "0010000124258736",
            "auth_code": "",
            "endpoint_id": 414,
            "id": 414
        },
        "sum_converted": {
            "amount": 200000,
            "currency": "EUR"
        },
        "code": "0",
        "message": "Success",
        "id": 55386010114429,
        "type": "refund",
        "status": "success",
        "date": "2024-01-24T06:24:45+0000",
        "sum_initial": {
            "amount": 200000
            "currency": "EUR"
        },
        "created_date": "2024-01-24T06:24:43+0000",
        "request_id": "abcaf52323381a-d988c158cc4b43046-00055387"
    }
}
```

## Передача произвольных сведений {#ru_pp_merchant_data}

### Общая информация {#section_f2q_4kv_fzb .section}

С помощью параметра `merchant_data` можно фиксировать расширенные сведения о составе заказа, информацию об использовании промокодов и бонусных баллов и другие актуальные данные.При этом можно комбинировать состав таких сведений со сведениями, передаваемыми в описании платежа \(в параметре `payment_description`\) и в информации для товарного чека \(в параметре `receipt_data`\). Это позволяет получать в оповещениях всю необходимую информацию без её дублирования в различных параметрах.

### Пример использования {#section_ung_wjx_y2c .section}

В качестве примера можно рассмотреть ситуацию, когда мерчанту, ведущему бизнес в сфере видеоигр, актуально обеспечить:

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

Специалисты мерчанта обращаются с такой задачей к курирующему менеджеру Ecommpay, после чего настраивается следующая схема работы:

1.  В каждом запросе на открытие Payment Page со стороны веб-сервиса мерчанта передаётся информация о приобретаемых услугах — в виде JSON-объекта в параметре `merchant_data`.

    В состав строки `merchant_data` включаются:

    -   массив `items`, в котором каждый элемент содержит артикул \(`sku`\), описание \(`description`\) и количество приобретаемых услуг \(`count`\);
    -   параметр `total_count` с общим количеством приобретаемых услуг или товарных позиций;
    -   параметр `user_id` с внутренним идентификатором пользователя.
2.  По результатам проведения каждого платежа информация из строки `merchant_data` передаётся к веб-сервису мерчанта в итоговом оповещении и становится доступной для просмотра в карточке платежа интерфейса Dashboard.
3.  На стороне веб-сервиса обеспечивается необходимая обработка получаемой информации вместе с другой информацией о проводимых платежах.

![](images/ecommpay/ru_pp_additional_data.svg "Оформление заказа в веб-сервисе")

![](images/ecommpay/ru_merchant_data_db.svg "Отображение информации в интерфейсе Dashboard")

### Подключение {#section_xf5_tkv_fzb .section}

Возможности применения параметра `merchant_data` для передачи и получения различных сведений следует согласовывать с курирующим менеджером Ecommpay. После согласований специалисты Ecommpay выполняют необходимые действия в платёжной платформе и уведомляют о готовностик включению расширенных сведений в оповещения и к отображению этих сведений в интерфейсе Dashboard.

### Формат данных {#section_tp5_rfc_nzb .section}

В запросах на открытие Payment Page для проведения платежей сведения в параметре `merchant_data` должны передаваться в виде JSON-объекта. При этом, поскольку параметр имеет строковый тип данных\(string\), для передачи JSON-объекта методом POST требуется экранировать символ `"` \(двойной штрих,U+0022\) путём постановки перед ним символа `\` \(косой обратной черты,U+005C\). Это необходимо, чтобы чётко разграничивать на уровне программного взаимодействия, какие кавычки закрывают строку, а какие относятся к содержанию JSON-объекта внутри строки. Вместе с тем, при отправке запросов методом GET экранировать содержимое JSON-объектов не обязательно \(поскольку корректная интерпретация данных в таких случаях возможна и без экранирования\).

В итоговых оповещениях о результатах платежей сведения из параметра `merchant_data` передаются в параметре `data` объекта `merchant`, с применением экранирования.

В следующих примерах содержимое параметра разбито на несколько строк для удобства чтения.

```language-json
"merchant_data": "{"items":[{"sku":"GM12-CC",
        "description":"10 Copper Coins","count":1},
        {"sku":"GM12-GC","description":"Golden Coin",
        "count":2}],"total_count":3,"user_id":"122"}"
```

```language-json
"merchant_data": "{\"items\":[{\"sku\":\"GM12-CC\",
        \"description\":\"10 Copper Coins\",\"count\":1},
        {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\",
        \"count\":2}],\"total_count\":3,\"user_id\":\"122\"}"
```

```language-json
"merchant": {
        "data": "{\"items\":[{\"sku\":\"GM12-CC\",
        \"description\":\"10 Copper Coins\",\"count\":1},
        {\"sku\":\"GM12-GC\",\"description\":\"Golden Coin\",
        \"count\":2}],\"total_count\":3,\"user_id\":\"122\"}" 
}
```