Передача дополнительных сведений об оплатах для их учёта на стороне веб-сервиса
Введение
В некоторых случаях при проведении платежей может быть актуально передавать не только обязательные и рекомендуемые со стороны провайдера параметры, но и те сведения, которые могут быть полезны в дальнейшем на стороне мерчанта (с привязкой к конкретным платежам и их статусам). Для таких ситуаций в структуре Payment Page API предусмотрены параметры, позволяющие передавать различные сведения в запросах и получать эти сведения вместе с другой информацией в составе итоговых оповещений.
Передача сведений о бронировании товаров и услуг
Общая информация
С помощью параметра booking_info
можно фиксировать сведения о бронировании, связанном с оплатой, и получать эти сведения в оповещениях от платёжной платформы. В отличие от используемых в отдельных индустриях «длинных записей» (подробнее) эта возможность может применяться более широко (например, для указания сведений о бронировании билетов на концерт) и гибко, без ограничений на категорию мерчанта (согласно коду Merchant Category Code, MCC) и требований к обязательности указания параметров. Вместе с тем, использование этой возможности не обеспечивает тех преимуществ, которые могут быть доступны при работе с «длинными записями», и при наличии вопросов о работе с этими возможностями можно обращаться к курирующему менеджеру ecommpay.
Параметр booking_info
может использоваться практически для всех целевых действий с прямым использованием платёжных карт и с использованием методов Apple Pay и Google Pay: в частности, для проведения оплат, выполнения блокировки средств, регистрации нерегулярных повторяемых оплат (экспресс-оплат и автооплат) и для проверки платёжных инструментов.
С помощью параметра booking_info
можно фиксировать в запросах сведения о бронировании товаров и услуг. Эта возможность доступна при проведении платежей с прямым использованием платёжных карт и с использованием методов Apple Pay и Google Pay.
Пример использования
В качестве примера можно рассмотреть ситуацию, когда мерчанту, ведущему бизнес в сфере музыкальных фестивалей, актуально обеспечить:
- сбор и обработку информации о бронированиях билетов на фестивали;
- оперативный доступ своих сотрудников к актуальной информации такого рода по каждому пользователю.
Для этого настраивается следующая схема работы:
- В каждом запросе на открытие Payment Page, подходящем для передачи сведений о бронировании, со стороны веб-сервиса передаются такие сведения — в параметре
booking_info
. В значении этого параметра указывается строка, полученная в результате кодирования алгоритмом Base64 JSON-объекта с параметрами бронирования.К таким параметрам могут относиться:
firstname
— имя получателя услуги, указанное при бронировании;surname
— фамилия получателя услуги, указанная при бронировании;email
— адрес электронной почты, указанный при бронировании;start_date
— дата начала действия забронированной услуги;end_date
— дата окончания действия забронированной услуги;description
— произвольное описание бронирования;total
— итоговая стоимость бронирования;pax
— количество лиц, для которых осуществлено бронирование;reference
— указатель забронированной услуги, в качестве которого могут выступать URL, название или код услуги в сервисе мерчанта;id
— идентификатор бронирования, уникальный в рамках сервиса мерчанта.
- По результатам выполнения соответствующей операции информация из параметра
booking_info
передаётся к веб-сервису мерчанта в итоговом оповещении. - На стороне веб-сервиса обеспечивается необходимая обработка получаемой информации вместе с другой информацией о выполняемых операциях.
Подключение
Указывать параметр booking_info
в запросах и получать передаваемые в нём сведения в оповещениях (при использовании типовой структуры оповещений) можно без согласований и каких-либо дополнительных действий. Эти возможности доступны по умолчанию.
Возможности использования параметра booking_info
доступны по умолчанию и не требуют отдельного подключения.
Формат данных
Параметр booking_info
может включаться в запросы на открытие Payment Page в виде строки, полученной в результате кодирования с применением алгоритма Base64 JSON-объекта booking_info
с необходимыми параметрами бронирования.
Параметр | Описание |
---|---|
|
Имя получателя услуги, указанное при бронировании |
|
Фамилия получателя услуги, указанная при бронировании |
|
Адрес электронной почты, указанный при бронировании |
|
Дата начала действия забронированной услуги, в формате ДД-ММ-ГГГГ |
|
Дата окончания действия забронированной услуги, в формате ДД-ММ-ГГГГ |
|
Произвольное описание бронирования |
|
Итоговая стоимость бронирования |
|
Количество лиц, для которых осуществлено бронирование |
|
Указатель забронированной услуги, в качестве которого могут выступать URL, название или код услуги в сервисе мерчанта |
|
Идентификатор бронирования, уникальный в рамках сервиса мерчанта |
"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" }
ewogICAgImZpcnN0bmFtZSI6ICJXaWxsaWFtIiwKICAgICJzdXJuYW1lIjogIkhlcnNjaGVsIiwKICAgICJlbWFpbCI6ICJyc2ZlbGxvd0BtYWlsLmNvbSIsCiAgICAic3RhcnRfZGF0ZSI6ICIxMi0wOC0yMDI2IiwKICAgICJlbmRfZGF0ZSI6ICIxMy0wOC0yMDI2IiwKICAgICJkZXNjcmlwdGlvbiI6ICJTaWRlcmlzIG11c2ljIGZlc3RpdmFsIGZ1bGwgcGFzcyIsCiAgICAidG90YWwiOiAyMDAwMDAsCiAgICAicGF4IjogNCwKICAgICJyZWZlcmVuY2UiOiAibXVzaWNmZXN0bGluayIsCiAgICAiaWQiOiAiODMiCn0=
{ "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, после чегоДля этого настраивается следующая схема работы:
- В каждом запросе на открытие Payment Page со стороны веб-сервиса мерчанта передаётся информация о приобретаемых услугах — в виде JSON-объекта в параметре
merchant_data
.В состав строки
merchant_data
включаются:- массив
items
, в котором каждый элемент содержит артикул (sku
), описание (description
) и количество приобретаемых услуг (count
); - параметр
total_count
с общим количеством приобретаемых услуг или товарных позиций; - параметр
user_id
с внутренним идентификатором пользователя.
- массив
- По результатам проведения каждого платежа информация из строки
merchant_data
передаётся к веб-сервису мерчанта в итоговом оповещении и становится доступной для просмотра в карточке платежа интерфейса Dashboard. - На стороне веб-сервиса обеспечивается необходимая обработка получаемой информации вместе с другой информацией о проводимых платежах.
Подключение
Возможности применения параметра merchant_data
для передачи и получения различных сведений следует согласовывать с курирующим менеджером ecommpay. После согласований специалисты ecommpay выполняют необходимые действия в платёжной платформе и уведомляют о готовности к включению расширенных сведений в оповещения и к отображению этих сведений в интерфейсе Dashboard.
Формат данных
В запросах на открытие Payment Page для проведения платежей сведения в параметре merchant_data
должны передаваться в виде JSON-объекта. При этом, поскольку параметр имеет строковый тип данных (string), для передачи JSON-объекта методом POST требуется экранировать символ "
(двойной штрих, U+0022) путём постановки перед ним символа \
(косой обратной черты, U+005C). Это необходимо, чтобы чётко разграничивать на уровне программного взаимодействия, какие кавычки закрывают строку, а какие относятся к содержанию JSON-объекта внутри строки. Вместе с тем, при отправке запросов методом GET экранировать содержимое JSON-объектов не обязательно (поскольку корректная интерпретация данных в таких случаях возможна и без экранирования).
В итоговых оповещениях о результатах платежей сведения из параметра merchant_data
передаются в параметре data
объекта merchant
, с применением экранирования.
В следующих примерах содержимое параметра разбито на несколько строк для удобства чтения.
"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"}"
"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\"}"
"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\"}" }