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

Введение

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

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

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

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

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

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

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

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

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

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

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

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

Подключение

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

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

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

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

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

Рис. 1. Пример данных из 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"}"
Рис. 2. Пример данных из 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\"}"
Рис. 3. Пример данных из итогового оповещения о результате оплаты (с экранированием)
"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\"}" 
}