Использование «длинной записи»

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

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

  • Ограничение на MCC-код — длинная запись используется только в туристической отрасли, поэтому платежи с этой записью доступны только для мерчантов с MCC-кодами 3501–3999 и 7011.
  • Обязательное наличие длинной записи в начальном запросе на оплату — длинная запись должна обязательно передаваться в начальном запросе. В последующих запросах ее использовать не обязательно. Если в начальном запросе длинная запись не передавалась, то при попытке передать длинную запись в любом из последующих запросов платежная платформа вернет ошибку.

Кроме того, использование длинной записи поддерживается только при проведении операций с использованием карт платёжных систем Visa и Mastercard.

Вся информация о бронировании упаковывается по определенным правилам в одно значение и передается в Payment Page в параметре addendum_data в дополнение к обычно передаваемым параметрам платежа. Далее рассказывается, как на основании информации о бронировании сформировать значение параметра addendum_data.

Создание значения параметра addendum_data

Перед размещением в параметре addendum_data информацию о бронировании нужно определенным образом преобразовать, чтобы получить одно значение, содержащее всю эту информацию. Далее рассказывается, как это сделать.

  1. Информация о бронировании размещается в JSON-объекте lodging. Подробно о параметрах и объектах, вложенных в lodging, см. Параметры длинной записи в Gate API.

    Вот пример JSON-объекта lodging с информацией о бронировании отеля:

    {
 "lodging": {
  "customer_service_toll_free_number": "88005553535", // Телефон поддержки клиентов отеля 
  "guest_name": "John Smith",        // Ф.И.О. гостя
  "check_in_date": "10-12-2019",     // Дата въезда в отель
  "check_out_date": "22-12-2019",    // Дата выезда из отеля
  "folio_number": "56265655ABC",     // Номер бронирования
  "fire_safety_act_indicator": true, // Класс пожарной безопасности отеля
  "room": {            // Объект с параметрами номера
  "rate": 12,                 // Стоимость суток проживания
  "number_of_nights": "12"    // Количество ночей
  },
  "charges": {            // Объект с суммами сборов
  "transportation": 1200,       // Сбор за услуги трансфера
  "internet_access": 4500       // Сбор за доступ к Интернету
  }
 }
}

  2. JSON-объект с информацией о бронировании кодируется с применением алгоритма Base64.

    Вот строка, полученная в результате кодирования примера JSON-объекта lodging, приведенного в п. 1 (перед кодированием комментарии были удалены):
    ewogImxvZGdpbmciOiB7CiAgImN1c3RvbWVyX3NlcnZpY2VfdG9sbF9mcmVlX251bWJlciI6ICI4ODAwNTU1Mz
UzNSIsCiAgImd1ZXN0X25hbWUiOiAiSm9obiBTbWl0aCIsCiAgImNoZWNrX2luX2RhdGUiOiAiMTAtMTItMjAx
OSIsCiAgImNoZWNrX291dF9kYXRlIjogIjIyLTEyLTIwMTkiLAogICJmb2xpb19udW1iZXIiOiAiNTYyNjU2NT
VBQkMiLAogICJmaXJlX3NhZmV0eV9hY3RfaW5kaWNhdG9yIjogdHJ1ZSwKICAicm9vbSI6IHsKICAicmF0ZSI6
IDEyLAogICJudW1iZXJfb2ZfbmlnaHRzIjogIjEyIgogIH0sCiAgImNoYXJnZXMiOiB7CiAgInRyYW5zcG9ydG
F0aW9uIjogMTIwMCwKICAiaW50ZXJuZXRfYWNjZXNzIjogNDUwMAogIH0KIH0KfQ==
Полученная таким образом строка передается в качестве значения параметра addendum_data. Этот параметр добавляется в состав прочих — обязательных и необязательных — параметров платежа до создания подписи. Вот пример запроса на открытие Payment Page для оплаты с использованием длинной записи (для простоты некоторые значения сокращены):
EPayWidget.run(
    { payment_id: 'X01254',     // Идентификатор платежа
      payment_amount: 20000,    // Сумма платежа
      payment_currency: 'USD',  // Валюта платежа
      project_id: 258,          // Идентификатор мерчанта
      customer_id: '123',       // Идентификатор пользователя
      addendum_data: "ewogImxvZGdpbmciOiB7CiAgImN1c3Rv...==" // Длинная запись
      signature: "kUi2x9dKHAVNU0FYlSCQ9vySO\/RLCvhtT...=="   // Подпись
    }
)

Ссылки по теме