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

Введение

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

Notice: При работе с Gate API можно использовать аналогичные возможности.

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

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

С помощью параметра booking_info можно фиксировать сведения о бронировании, связанном с оплатой, и получать эти сведения в оповещениях от платёжной платформы. В отличие от используемых в отдельных индустриях «длинных записей» (подробнее) эта возможность может применяться более широко (например, для указания сведений о бронировании билетов на концерт) и гибко, без ограничений на категорию мерчанта (согласно коду Merchant Category Code, MCC) и требований к обязательности указания параметров. Вместе с тем, использование этой возможности не обеспечивает тех преимуществ, которые могут быть доступны при работе с «длинными записями», и при наличии вопросов о работе с этими возможностями можно обращаться к курирующему менеджеру ecommpay.

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

С помощью параметра booking_info можно фиксировать в запросах сведения о бронировании товаров и услуг. Эта возможность доступна при проведении платежей с прямым использованием платёжных карт и с использованием методов Apple Pay и Google Pay.

Пример использования

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

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

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

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

    К таким параметрам могут относиться:

    • firstname — имя получателя услуги, указанное при бронировании;
    • surname — фамилия получателя услуги, указанная при бронировании;
    • email — адрес электронной почты, указанный при бронировании;
    • start_date — дата начала действия забронированной услуги;
    • end_date — дата окончания действия забронированной услуги;
    • description — произвольное описание бронирования;
    • total — итоговая стоимость бронирования;
    • pax — количество лиц, для которых осуществлено бронирование;
    • reference — указатель забронированной услуги, в качестве которого могут выступать URL, название или код услуги в сервисе мерчанта;
    • id — идентификатор бронирования, уникальный в рамках сервиса мерчанта.
  2. По результатам выполнения соответствующей операции информация из параметра booking_info передаётся к веб-сервису мерчанта в итоговом оповещении.
  3. На стороне веб-сервиса обеспечивается необходимая обработка получаемой информации вместе с другой информацией о выполняемых операциях.

Подключение

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

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

Формат данных

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

Параметр Описание

firstname
string

Имя получателя услуги, указанное при бронировании

surname
string

Фамилия получателя услуги, указанная при бронировании

email
string

Адрес электронной почты, указанный при бронировании

start_date
string

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

end_date
string

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

description
string

Произвольное описание бронирования

total
integer

Итоговая стоимость бронирования

pax
integer

Количество лиц, для которых осуществлено бронирование

reference
string

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

id
string

Идентификатор бронирования, уникальный в рамках сервиса мерчанта
Рис. 1. Пример JSON-объекта
"booking_info": {
    "firstname": "William",
    "surname": "Herschel",
    "email": "rsfellow@mail.com",
    "start_date": "12-08-2026",
    "end_date": "13-08-2026",
    "description": "Sideris music festival full pass",
    "total": 200000,
    "pax": 4,
    "reference": "musicfestlink",
    "id": "83"
}
Рис. 2. Пример строки
ewogICAgImZpcnN0bmFtZSI6ICJXaWxsaWFtIiwKICAgICJzdXJuYW1lIjogIkhlcnNjaGVsIiwKICAgICJlbWFpbCI6ICJyc2ZlbGxvd0BtYWlsLmNvbSIsCiAgICAic3RhcnRfZGF0ZSI6ICIxMi0wOC0yMDI2IiwKICAgICJlbmRfZGF0ZSI6ICIxMy0wOC0yMDI2IiwKICAgICJkZXNjcmlwdGlvbiI6ICJTaWRlcmlzIG11c2ljIGZlc3RpdmFsIGZ1bGwgcGFzcyIsCiAgICAidG90YWwiOiAyMDAwMDAsCiAgICAicGF4IjogNCwKICAgICJyZWZlcmVuY2UiOiAibXVzaWNmZXN0bGluayIsCiAgICAiaWQiOiAiODMiCn0=
Рис. 3. Пример данных из итогового оповещения о результате оплаты
{
    "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": {    // Объект с информацией о бронировании
        "firstname": "William",
        "surname": "Herschel",
        "email": "rsfellow@mail.com",
        "start_date": "12-08-2026",
        "end_date": "13-08-2026",
        "description": "Sideris music festival full pass",
        "total": 200000,
        "pax": 4,
        "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"
    }
}

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

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

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

Пример использования

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

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

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

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

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

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

Подключение

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

Формат данных

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

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

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

Рис. 6. Пример данных из GET-запроса на открытие Payment Page (без экранирования)
"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"}"
Рис. 7. Пример данных из POST-запроса на открытие Payment Page (с экранированием)
"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\"}"
Рис. 8. Пример данных из итогового оповещения о результате оплаты (с экранированием)
"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\"}" 
}