Формат запросов на проведение платежей через Payment Page

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

При переходе к 3‑D Secure 2 для запросов на открытие платёжной формы используется стандартный формат с поддержкой параметров, которые не являются обязательными, но рекомендуются для повышения вероятности выбора варианта аутентификации frictionless flow. К таким параметрам относятся как новые параметры, так и поддержанные ранее.

Общее описание форматов запросов при работе через Payment Page представлено в разделе Описание Payment Page API, а описание параметров, использование которых рекомендуется для повышения вероятности выбора варианта аутентификации frictionless flow, — в этом разделе.

Новый параметр payment_merchant_risk

Параметр payment_merchant_risk используется при работе через Payment Page и представляет собой строку, полученную в результате кодирования с применением алгоритма Base64, с информацией о деталях покупки пользователя и о предпочтительном для мерчанта варианте аутентификации. Для получения такой строки необходимо:

  1. Сформировать JSON-объект payment с необходимыми объектами и параметрами, в качестве которых можно использовать любые параметры из представленных в примере.

    Рис.: Пример JSON-объекта

    { 
      "payment":{ 
        "reorder":"01",
        "preorder_purchase":"01",
        "preorder_date":"01-10-2019",
        "challenge_indicator":"01",
        "challenge_window":"01",
        "gift_card":{ 
          "amount":12345,
          "currency":"USD",
          "count":1
        }
      }
    }
    Табл. 1. Описание параметров
    ПАРАМЕТР ТИП ОПИСАНИЕ
    challenge_indicator string Указатель предпочтения по использованию варианта аутентификации challenge flow. Возможные значения:
    • 01 — без предпочтений,
    • 02 — предпочтительно не выполнять,
    • 03 — предпочтительно выполнять,
    • 04 — обязательно выполнять
    challenge_window string Размер окна для открытия страницы аутентификации. Возможные значения:
    • 01 — 250 x 400 пикселей,
    • 02 — 390 x 400 пикселей,
    • 03 — 500 x 600 пикселей,
    • 04 — 600 x 400 пикселей,
    • 05 — полноэкранный режим
    preorder_date string Планируемая дата поступления товара или услуги в формате ДД-ММ-ГГГГ
    preorder_purchase string Индикатор предварительного заказа. Возможные значения:
    • 01 — не является предварительным заказом,
    • 02 — является предварительным заказом
    reorder string Индикатор первичной или повторной покупки данного товара или услуги пользователем. Возможные значения:
    • 01 — первичная покупка,
    • 02 — повторная покупка
    gift_card — объект с информацией об оплате предоплаченными или подарочными картами
    amount integer Общая сумма оплаты предоплаченными или подарочными картами в минорных единицах валюты
    currency string Код валюты оплаты предоплаченными или подарочными картами в формате ISO 4217 alpha-3 (например, GBP)
    count integer Количество предоплаченных или подарочных карт, использованных для оплаты
  2. Закодировать JSON-объект с применением алгоритма Base64.

    Рис.: Пример строки

    eyAKICAicGF5bWVudCI6eyAKICAgICJyZW9yZGVyIjoiMDEiLAogICAgInByZW9yZGVyX3B1cmNoYXNlIjoiMDEiLAogICAgInByZW9yZGVyX2RhdGUiOiIwMS0xMC0yMDE5IiwKICAgICJjaGFsbGVuZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgImNoYWxsZW5nZV93aW5kb3ciOiIwMSIsCiAgICAiZ2lmdF9jYXJkIjp7IAogICAgICAiYW1vdW50IjoxMjM0NSwKICAgICAgImN1cnJlbmN5IjoiVVNEIiwKICAgICAgImNvdW50IjoxCiAgICB9CiAgfQp9Cg==

Полученная таким образом строка передаётся в параметре payment_merchant_risk запроса на открытие платёжной формы в числе прочих параметров.

Новый параметр customer_account_info

Параметр customer_account_info используется при работе через Payment Page и представляет собой строку, полученную в результате кодирования с применением алгоритма Base64, с информацией об учётной записи пользователя на стороне веб-сервиса и о контактных данных пользователя. Для получения такой строки необходимо:

  1. Сформировать JSON-объект customer с необходимыми объектами и параметрами, в качестве которых можно использовать любые параметры из представленных в примере.

    Рис.: Пример JSON-объекта

    { 
      "customer":{ 
        "address_match":Y,
        "home_phone":"79105211111",
        "work_phone":"74955211111",
        "account":{ 
          "additional":"gamer12345",
          "age_indicator":"01",
          "date":"01-10-2019",
          "change_indicator":"01",
          "change_date":"01-10-2019",
          "pass_change_indicator":"01",
          "pass_change_date":"01-10-2019",
          "purchase_number":12,
          "provision_attempts":16,
          "activity_day":22,
          "activity_year":222,
          "payment_age_indicator":"01",
          "payment_age":"01-10-2019",
          "suspicious_activity":"01",
          "auth_method":"01",
          "auth_time":"01-10-201913:12",
          "auth_data":"login_0102"
        }
      }
    }
    Табл. 2. Описание параметров
    ПАРАМЕТР ТИП ОПИСАНИЕ
    address_match string

    Указатель совпадения платёжного адреса пользователя с адресом доставки, указанным в объекте shipping.

    Возможные значения:
    • Y—совпадает,
    • N—не совпадает
    home_phone string Номер домашнего телефона пользователя, может содержать только цифры, от четырёх до двадцати четырёх (например, 44991234567)
    work_phone string Номер рабочего телефона пользователя, может содержать только цифры, от четырёх до двадцати четырёх (например, 44997654321)
    account — объект, содержащий информацию об учётной записи пользователя на стороне мерчанта
    additional string Дополнительная информация об учётной записи пользователя, например её идентификатор; в произвольном формате с использованием до шестидесяти четырёх символов
    activity_day integer Количество попыток проведения оплаты за последние 24 часа, не более трёх символов (999)
    activity_year integer Количество попыток проведения оплаты за последние 365 дней, не более трёх символов (999)
    age_indicator string Количество дней с момента создания учётной записи пользователя. Возможные значения:
    • 01 — платёж проводится без аутентификации в учётной записи,
    • 02 — учётная запись создана в день проведения платежа,
    • 03 — менее 30 дней,
    • 04 — от 30 до 60 дней,
    • 05 — более 60 дней
    auth_data string Дополнительная информация об аутентификации на стороне веб-сервиса в произвольном формате. Параметр может содержать не более 255 символов
    auth_method string Указатель способа последней аутентификации пользователя на стороне веб-сервиса. Возможные значения:
    • 01 — доступ без аутентификации;
    • 02 — аутентификация с использованием данных, сохранённых на стороне мерчанта;
    • 03 — аутентификация с использованием Federated ID (например, Google Account или Facebook);
    • 04 — аутентификация с использованием аутентификатора, соответствующего стандартам Fast IDentity Online (FIDO)
    auth_time string Дата и время последней аутентификации пользователя на стороне веб-сервиса в формате ДД-ММ-ГГГГчч:мм
    date string Дата создания учётной записи в формате ДД-ММ-ГГГГ
    change_date string Дата последних изменений в учётной записи, за исключением изменения или сброса пароля, в формате ДД-ММ-ГГГГ
    change_indicator string Количество дней с момента последних изменений в учётной записи, за исключением изменения или сброса пароля. Возможные значения:
    • 01 — изменения в день проведения платежа,
    • 02 — менее 30 дней,
    • 03 — от 30 до 60 дней,
    • 04 — более 60 дней
    pass_change_date string Дата последнего изменения или сброса пароля в формате ДД-ММ-ГГГГ
    pass_change_indicator string Количество дней с момента последнего изменения или сброса пароля. Возможные значения:
    • 01 — пароль не был изменён или сброшен,
    • 02 — пароль был изменён или сброшен в день проведения платежа,
    • 03 — менее 30 дней,
    • 04 — от 30 до 60 дней,
    • 05 — более 60 дней
    payment_age string Дата добавления платёжных данных карты в формате ДД-ММ-ГГГГ
    payment_age_indicator string Количество дней с момента сохранения данных платёжной карты, используемой для проведения платежа, в учётной записи пользователя. Возможные значения:
    • 01 — платёж проводится без аутентификации в учётной записи,
    • 02 — данные карты сохранены в день проведения платежа,
    • 03 — менее 30 дней,
    • 04 — от 30 до 60 дней,
    • 05 — более 60 дней
    provision_attempts integer Количество попыток сохранения новых платёжных данных карты за последние 24 часа, не более трёх символов (999)
    purchase_number integer Количество покупок, совершённых через эту учётную запись за последние 6 месяцев, не более четырёх символов (9999)
    suspicious_activity string Индикатор подозрительной активности. Возможные значения:
    • 01 — без подозрений,
    • 02 — с подозрительной активностью
  2. Закодировать JSON-объект с применением алгоритма Base64.

    Рис.: Пример строки

    eyAKICAiY3VzdG9tZXIiOnsgCiAgICAiYWRkcmVzc19tYXRjaCI6dHJ1ZSwKICAgICJob21lX3Bob25lIjoiNzkxMDUyMTExMTEiLAogICAgIndvcmtfcGhvbmUiOiI3NDk1NTIxMTExMSIsCiAgICAiYWNjb3VudCI6eyAKICAgICAgImFkZGl0aW9uYWwiOiJnYW1lcjEyMzQ1IiwKICAgICAgImFnZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJkYXRlIjoiMDEtMTAtMjAxOSIsCiAgICAgICJjaGFuZ2VfaW5kaWNhdG9yIjoiMDEiLAogICAgICAiY2hhbmdlX2RhdGUiOiIwMS0xMC0yMDE5IiwKICAgICAgInBhc3NfY2hhbmdlX2luZGljYXRvciI6IjAxIiwKICAgICAgInBhc3NfY2hhbmdlX2RhdGUiOiIwMS0xMC0yMDE5IiwKICAgICAgInB1cmNoYXNlX251bWJlciI6MTIsCiAgICAgICJwcm92aXNpb25fYXR0ZW1wdHMiOjE2LAogICAgICAiYWN0aXZpdHlfZGF5IjoyMiwKICAgICAgImFjdGl2aXR5X3llYXIiOjIyMjIsCiAgICAgICJwYXltZW50X2FnZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJwYXltZW50X2FnZSI6IjAxLTEwLTIwMTkiLAogICAgICAic3VzcGljaW91c19hY3Rpdml0eSI6IjAxIiwKICAgICAgImF1dGhfbWV0aG9kIjoiMDEiLAogICAgICAiYXV0aF90aW1lIjoiMDEtMTAtMjAxOTEzOjEyIiwKICAgICAgImF1dGhfZGF0YSI6ImxvZ2luXzAxMDIiCiAgICB9CiAgfQp9

Полученная таким образом строка передаётся в параметре customer_account_info запроса на открытие платёжной формы в числе прочих параметров.

Новый параметр customer_shipping

Параметр customer_shipping используется при работе через Payment Page и представляет собой строку, полученную в результате кодирования с применением алгоритма Base64, с информацией о доставке товара или услуги пользователю. Для получения такой строки необходимо:

  1. Сформировать JSON-объект customer с объектом shipping и необходимыми параметрами, в качестве которых можно использовать любые параметры из представленных в примере.

    Рис.: Пример JSON-объекта

    { 
      "customer":{ 
        "shipping":{ 
          "type":"01",
          "delivery_time":"01",
          "delivery_email":"test@gmail.com",
          "address_usage_indicator":"01",
          "address_usage":"01-10-2019",
          "city":"Moscow",
          "country":"RU",
          "address":"Lenina street 12",
          "postal":"109111",
          "region_code":"RU",
          "name_indicator":"01"
        }
      }
    }
    Табл. 3. Описание параметров
    ПАРАМЕТР ТИП ОПИСАНИЕ
    shipping — объект, содержащий информацию о доставке
    address string Адрес доставки, не более ста пятидесяти символов
    address_usage string Дата первого использования адреса доставки, указанного в параметрах этого объекта, в формате ДД-ММ-ГГГГ
    address_usage_indicator string Количество дней с момента первого использования адреса доставки, указанного в параметрах этого объекта. Возможные значения:
    • 01 — указанный адрес используется впервые,
    • 02 — менее 30 дней назад,
    • 03 — от 30 до 60 дней назад,
    • 04 — более 60 дней назад
    city string Название города доставки, не более пятидесяти символов
    country string Код страны доставки в формате ISO 3166-1 alpha-2 (например, GB)
    delivery_email string Адрес электронной почты в случае доставки на этот адрес. Может содержать не более 255 символов
    delivery_time string Срок доставки. Возможные значения:
    • 01 — электронная доставка в день покупки,
    • 02 — доставка в день покупки,
    • 03 — доставка на следующий день после покупки,
    • 04 — доставка более чем через один день после покупки
    name_indicator string Индикатор совпадения имени пользователя с именем получателя. Возможные значения:
    • 01 — имена совпадают,
    • 02 — имена не совпадают
    postal string Почтовый индекс доставки, не более шестнадцати символов
    region_code string Код штата, провинции или региона страны в формате ISO 3166-2, например SPE для Санкт-Петербурга.

    При указании значения этого параметра также необходимо указать значение параметра country в объекте shipping

    type string Способ доставки, выбранный пользователем. Возможные значения:
    • 01 — доставка на платёжный адрес держателя карты;
    • 02 — доставка на другой подтверждённый адрес;
    • 03 — доставка на адрес, не совпадающий с платёжным и не являющийся подтверждённым;
    • 04 — доставка в магазин;
    • 05 — электронная доставка;
    • 06 — без доставки (например, в случае покупки билетов на мероприятие);
    • 07 — другое
  2. Закодировать JSON-объект с применением алгоритма Base64.

    Рис.: Пример строки

    eyAKICAiY3VzdG9tZXIiOnsgCiAgICAic2hpcHBpbmciOnsgCiAgICAgICJ0eXBlIjoiMDEiLAogICAgICAiZGVsaXZlcnlfdGltZSI6IjAxIiwKICAgICAgImRlbGl2ZXJ5X2VtYWlsIjoidGVzdEBnbWFpbC5jb20iLAogICAgICAiYWRkcmVzc191c2FnZV9pbmRpY2F0b3IiOiIwMSIsCiAgICAgICJhZGRyZXNzX3VzYWdlIjoiMDEtMTAtMjAxOSIsCiAgICAgICJjaXR5IjoiTW9zY293IiwKICAgICAgImNvdW50cnkiOiJSVSIsCiAgICAgICJhZGRyZXNzIjoiTGVuaW5hIHN0cmVldCAxMiIsCiAgICAgICJwb3N0YWwiOiIxMDkxMTEiLAogICAgICAicmVnaW9uX2NvZGUiOiJSVSIsCiAgICAgICJuYW1lX2luZGljYXRvciI6IjAxIgogICAgfQogIH0KfQ==

Полученная таким образом строка передаётся в параметре customer_shipping запроса на открытие платёжной формы в числе прочих параметров.

Новый параметр customer_mpi_result

Параметр customer_mpi_result используется при работе через Payment Page и представляет собой строку, полученную в результате кодирования с применением алгоритма Base64, с данными о предыдущей аутентификации пользователя. Для получения такой строки необходимо:

  1. Сформировать JSON-объект customer с объектом mpi_result и необходимыми параметрами, в качестве которых можно использовать любые параметры из представленных в примере.

    Рис.: Пример JSON-объекта

    { 
      "customer":{ 
        "mpi_result":{ 
          "acs_operation_id":"00000000-0005-5a5a-8000-016d3ea31d54",
          "authentication_flow":"01",
          "authentication_timestamp":"201812141050"
        }
      }
    }
    Табл. 4. Описание параметров
    ПАРАМЕТР ТИП ОПИСАНИЕ
    mpi_result — объект с данными о предыдущей аутентификации пользователя
    acs_operation_id string Идентификатор предыдущей операции пользователя на стороне эмитента, не более тридцати шести символов. В качестве этого идентификатора необходимо использовать значение, полученное в параметре acs_operation_id оповещения о результате проведения предыдущего платежа
    authentication_flow string

    Указатель варианта предыдущего прохождения аутентификации пользователем, полученное в параметре authentication_flow оповещения о результате проведения предыдущего платежа.

    Возможные значения:

    • 01 — frictionless flow,
    • 02 — challenge flow
    authentication_timestamp string Дата и время предыдущей успешной аутентификации пользователя. В качестве значения необходимо использовать данные, полученные в параметре mpi_timestamp оповещения о результате проведения предыдущего платежа
  2. Закодировать JSON-объект с применением алгоритма Base64.

    Рис.: Пример строки

    eyAKICAiY3VzdG9tZXIiOnsgCiAgICAibXBpX3Jlc3VsdCI6eyAKICAgICAgImFjc19vcGVyYXRpb25faWQiOiIwMDAwMDAwMC0wMDA1LTVhNWEtODAwMC0wMTZkM2VhMzFkNTQiLAogICAgICAiYXV0aGVudGljYXRpb25fZmxvdyI6IjAxIiwKICAgICAgImF1dGhlbnRpY2F0aW9uX3RpbWVzdGFtcCI6IjIwMTgxMjE0MTA1MCIKICAgIH0KICB9Cn0=

Полученная таким образом строка передаётся в параметре customer_mpi_result запроса на открытие платёжной формы в числе прочих параметров.

Новый параметр billing_region_code

ПАРАМЕТР ТИП ОПИСАНИЕ
billing_region_code string Код штата, провинции или региона страны в формате ISO 3166-2, например MOS для Московской области.

При указании значения этого параметра также необходимо указать значение параметра billing_country

Ранее поддержанные параметры

Для повышения вероятности выбора аутентификации варианта аутентификации frictionless flow в запросах на открытие платёжной формы рекомендуется использовать не только новые параметры, но и некоторые из параметров, реализованных ранее. Эти параметры перечислены далее.

ПАРАМЕТР ТИП ОПИСАНИЕ
billing_address string Улица платёжного адреса пользователя
billing_city string Город платёжного адреса пользователя
billing_country string Страна платёжного адреса пользователя в формате ISO 3166-1 alpha-2
billing_postal string Почтовый индекс платёжного адреса пользователя
customer_email string Адрес электронной почты пользователя
customer_phone string Номер телефона пользователя, может содержать только цифры, от четырёх до двадцати четырёх

Описание этих параметров также представлено в разделе Параметры открытия платежной формы Payment Page.