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

Введение

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

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

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

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

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

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

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

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

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

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

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

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

Подключение

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

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

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

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

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

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