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

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

**На уровень выше:**[Дополнительные возможности](ru_Gate_Additional_capabilities.md)

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

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

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

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

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

С помощью объекта `booking_info` можно фиксировать в запросах сведения о бронированиях, связанных с оплатами, и получать эти сведения в оповещениях от платёжной платформы. В отличие от используемых в отдельных индустриях «длинных записей» \([подробнее](ru_gate_addendum.md#)\) эта возможность может применяться более широко \(например, для указания сведений о бронировании билетов на концерты\) и гибко — без ограничений на категорию мерчанта \(согласно коду [Merchant Category Code, MCC](ru_glossary.md#)\). Вместе с тем, использование объекта `booking_info` не обеспечивает тех преимуществ, которые могут быть доступны при работе с «длинными записями», и при наличии вопросов о работе с этими возможностями можно обращаться к курирующему менеджеру 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_iyy_gwf_g1c .section}

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

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

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

1.  В каждом запросе к Gate API со стороны веб-сервиса мерчанта в объекте `booking_info` передаются следующие сведения о бронировании.
    -   Массив `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` объекта `booking_info` должны передаваться даты начала и окончания забронированной услуги в целом, а в параметрах `start_date` и `end_date` массива `items` — даты начала и окончания отдельных её составляющих.

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

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

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

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

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

Объект `booking_info` может включаться в запросы к различным конечным точкам и в оповещения о результатах операций, при этом его структура определяется [моделью](https://api-developers.ecommpay.com/api.html#/7f6ce1c65f45f-booking-info), а его расположение в структуре запросов — спецификацией этих конечных точек.

-   Для разовых одностадийных оплат:
    -   [/v2/payment/card/sale](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale)— с прямым указанием платёжных данных;
    -   [/v2/payment/card/sale/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-saved)— с указанием платёжных данных через идентификаторы;
    -   [/v2/payment/card/sale/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-sale-token)— с указанием платёжных данных через токены.
-   Для разовых двухстадийных оплат:
    -   [/v2/payment/card/auth](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth)— с прямым указанием платёжных данных;
    -   [/v2/payment/card/auth/saved](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-saved)— с указанием платёжных данных через идентификаторы;
    -   [/v2/payment/card/auth/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-auth-token)— с указанием платёжных данных через токены;
    -   [/v2/payment/card/incremental](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-incremental)— для увеличения суммы заблокированных в рамках разовых двухстадийных оплат средств пользователя.
-   Для оплат по платёжным ссылкам:
    -   [/v2/payment/invoice/create](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-create)— без указания платёжных данных в запросе;
    -   [/v2/payment/invoice/card/token/create](https://api-developers.ecommpay.com/api-specification/payment-links/post-v2-payment-invoice-card-token-create)— с указанием платёжных данных через токены.
-   Для повторяемых оплат:
    -   [/v2/payment/card/recurring](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-recurring).
-   Для проверки платёжных инструментов:
    -   [/v2/payment/card/account\_verification](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification)— с прямым указанием платёжных данных;
    -   [/v2/payment/card/account\_verification/token](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-account-verification-token)— с указанием данных через токены.
-   Для возвратов средств после оплат:
    -   [/v2/payment/card/refund](https://api-developers.ecommpay.com/api-specification/card-payments/post-v2-payment-card-refund).

-   [/v2/payment/applepay/sale](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-sale)— для разовых одностадийных оплат;
-   [/v2/payment/applepay/auth](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-auth)— для разовых двухстадийных оплат;
-   [/v2/payment/applepay/recurring](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-recurring)— для повторяемых оплат;
-   [/v2/payment/applepay/account\_verification](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-account-verification)— для проверки платёжных инструментов;
-   [/v2/payment/applepay/refund](https://api-developers.ecommpay.com/api-specification/apple-pay/post-v2-payment-applepay-refund)— для возвратов средств после оплат.

-   [/v2/payment/googlepay/sale](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-sale)— для разовых одностадийных оплат;
-   [/v2/payment/googlepay/auth](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-auth)— для разовых двухстадийных оплат;
-   [/v2/payment/googlepay/recurring](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-recurring)— для повторяемых оплат;
-   [/v2/payment/googlepay/account\_verification](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-account-verification)— для проверки платёжных инструментов;
-   [/v2/payment/googlepay/refund](https://api-developers.ecommpay.com/api-specification/google-pay/post-v2-payment-googlepay-refund)— для возвратов средств после оплат.

В итоговых оповещениях о результатах операций сведения из объекта `booking_info` передаются в таком же виде \(как и в запросах\) в объекте с названием `booking info`.

```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"
}
```

```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_gate_merchant_data}

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

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

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

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

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

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

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

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

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

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

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

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

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

В запросах к Gate для проведения платежей сведения в параметре `merchant.data` должны передаваться в виде JSON-объекта. При этом, поскольку параметр имеет строковый тип данных\(string\), для передачи JSON-объекта методом POST требуется экранировать символ `"` \(двойной штрих,U+0022\) путём постановки перед ним символа `\` \(косой обратной черты,U+005C\).Это необходимо, чтобы чётко разграничивать на уровне программного взаимодействия, какие кавычки закрывают строку, а какие относятся к содержанию 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\"}" 
}
```