Организация взаимодействия

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

Платёжная форма Payment Page допускает различные варианты её использования для проведения оплат и выполнения других целевых действий. Так, для вызова формы можно работать напрямую с Payment Page API или же использовать подключаемую библиотеку ECommPay, а открытие формы может осуществляться в отдельной вкладке браузера или же непосредственно на странице веб-сервиса. И так далее. Вариативность работы Payment Page описана в разделе Общая информация, а в данном разделе представлена информация о порядке и технических аспектах интеграции через Payment Page.

К базовым условиям для работы с Payment Page независимо от используемых технических решений можно отнести следующие:

  • вызов платёжной формы должен осуществляться с использованием протоколов HTTP версии не ниже 1.1 и TLS версии не ниже 1.2;
  • данные в запросах и оповещениях должны кодироваться и обрабатываться с использованием кодировки UTF-8;
  • запросы должны отправляться на базовый адрес — https://paymentpage.ecommpay.com;
  • в качестве пользовательского браузера могут использоваться актуальные версии таких браузеров, как Chrome, Safari, Opera, Firefox, Microsoft Edge, Internet Explorer, Yandex Browser, QQ, MIUI, Samsung Internet, 360 и ряда других.

Подробную информацию о работе Payment Page в разных средах можно получить у специалистов технической поддержки ECommPay (support@ecommpay.com), а информацию о вариантах интеграции, схемах работы и форматах запросов — в этом разделе.

Порядок интеграции

Для интеграции с платёжной платформой ECommPay через Payment Page необходимо:

  1. Решить организационные вопросы, касающиеся взаимодействия с ECommPay:

    1. Если у компании нет идентификатора проекта и секретного ключа для взаимодействия с ECommPay — отправить заявку на подключение.
    2. Для проведения платежей с использованием платёжных карт — предоставить курирующему менеджеру ECommPay копию сертификата или лист самооценки соответствия требованиям PCI DSS. С вопросами о заполнении листа самооценки можно обращаться к курирующему менеджеру ECommPay.
    3. При необходимости поддержать индивидуальный дизайн платёжной формы — согласовать с курирующим менеджером ECommPay условия реализации такого дизайна и необходимость проведения приёмки результатов.
    4. Согласовать со специалистами технической поддержки ECommPay порядок и сроки интеграции, тестирования и запуска в работу. В рамках согласования порядка тестирования могут быть согласованы возможности проведения тестовых платежей с использованием платёжных карт, а также некоторых из альтернативных методов.
  2. Выполнить подготовительные технические работы, собственными средствами или с использованием специализированных компонентов, предоставляемых ECommPay:

    1. Если требуется индивидуальный дизайн платёжной формы — разработать макет в соответствии с требованиями, перечисленными в разделе Индивидуальный дизайн, и согласовать его со специалистами технической поддержки.
    2. Установить и подключить необходимые библиотеки и (или) плагины.
    3. Обеспечить возможности сбора параметров, необходимых для выполнения целевого действия, а также формирования и отправки запросов на открытие Payment Page на стороне клиентской части веб-сервиса.
    4. Обеспечить подписывание данных и корректное реагирование на оповещения на стороне серверной части веб-сервиса.
  3. Совместно со специалистами технической поддержки ECommPay протестировать выполнение целевых действий и запустить техническое решение в работу.

    После тестирования и мониторинга, когда подтверждается корректность выполнения целевых действий на рабочем трафике, специалисты технической поддержки переводят работу с веб-сервисом в режим штатной поддержки.

При возникновении вопросов о работе с Payment Page на этапах 2 и 3 можно обращаться в службу технической поддержки ECommPay support@ecommpay.com.

Схема взаимодействия

При использовании Payment Page выполнение любого целевого действия подразумевает взаимодействия между тремя основными сторонами: пользователем, веб-сервисом и Payment Page. Эти взаимодействия осуществляются следующим образом:

  • Взаимодействие веб-сервиса и Payment Page строится на обмене HTTP-сообщениями по принципу «запрос-ответ». В такой схеме от клиентской части веб-сервиса к Payment Page отправляются запросы, а от Payment Page отправляются синхронные ответы к клиентской части веб-сервиса и асинхронные оповещения к серверной части веб-сервиса. Как правило, отправляются итоговые оповещения о результатах выполнения целевых действий, но в некоторых случаях могут отправляться и промежуточные оповещения, например при выполнении пользователем повторных попыток ввода данных. Кроме того, со стороны веб-сервиса может использоваться отслеживание интерфейсных событий в Payment Page, контролируемых с помощью встраиваемой библиотеки.
  • Взаимодействие пользователя и Payment Page осуществляется через пользовательский интерфейс платёжной формы и технически также основано на обмене HTTP-сообщениями по принципу «запрос-ответ» между пользовательским браузером и Payment Page.

Порядок взаимодействия между этими и другими сторонами представлен далее на схеме.

Рис.: Порядок взаимодействия

  1. Пользователь на стороне клиентской части веб-сервиса инициирует выполнение целевого действия.
  2. На стороне клиентской части веб-сервиса выполняется сбор параметров, необходимых для формирования запроса на открытие Payment Page, и их передача в серверную часть веб-сервиса.
  3. На стороне серверной части веб-сервиса выполняется обработка поступившего запроса:
    • проверка параметров;
    • дополнение полученных параметров хранящейся на стороне серверной части информацией, если это необходимо;
    • формирование подписи к набору параметров.
  4. От серверной части веб-сервиса к его клиентской части направляется ответ на запрос.
  5. На стороне клиентской части выполняется приём ответа, а затем формирование и отправка на заданный URL ECommPay запроса на открытие Payment Page.
  6. Запрос на открытие Payment Page поступает в платёжную платформу.
  7. В платёжной платформе выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
  8. Осуществляется подготовка Payment Page согласно настройкам проекта и параметрам вызова.
  9. Пользователю отображается подготовленная платёжная форма.
  10. Пользователь выполняет необходимые действия.
  11. Запрос на проведение платежа поступает в платёжную платформу.
  12. Выполняются дальнейшая обработка запроса и его отправка в платёжную среду.
  13. На стороне платёжной среды выполняется обработка платежа.
  14. От платёжной среды к платёжной платформе направляется уведомление о результате платежа.
  15. От платёжной платформы к веб-сервису направляется оповещение о результате платежа.
  16. От платёжной платформы к Payment Page направляется информация о результате проведения платежа.
  17. Результат платежа отображается пользователю на Payment Page.

Настройка веб-сервиса

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

Для начала работы с Payment Page на стороне веб-сервиса должны быть обеспечены:

  • сбор параметров, необходимых для проведения платежа;
  • формирование подписи;
  • открытие Payment Page;
  • обработка оповещений;
  • корректное реагирование на оповещения с отправкой ответов об их приёме.

Для этого можно использовать как только собственные решения, так и специализированные компоненты, предоставляемые ECommPay: подключаемую JavaScript-библиотеку, SDK для проектов на разных языках программирования и подключаемые модули для сайтов на базе ряда распространённых CMS. Использование таких компонентов помогает полностью или частично снять необходимость в задействовании собственных решений.

С помощью компонентов, предоставляемых ECommPay, могут выполняться следующие действия:

  JavaScript-библиотека SDK для веб-сервисов SDK для мобильных приложений Плагины для CMS
  • Сбор параметров
+ +
  • Формирование подписи
+ +
  • Открытие Payment Page
+ + +
  • Обработка оповещений
+ +
  • Реагирование на оповещения
+

Информация о настройке веб-сервиса с использованием собственных решений и каждого из специализированных компонентов, предоставляемых ECommPay, представлена далее.

Использование собственных решений

Для настройки взаимодействия с Payment Page с использованием собственных решений на стороне веб-сервиса необходимо обеспечить выполнение всех требуемых действий в клиентской и серверной частях.

  1. На стороне клиентской части веб-сервиса:
    • Подготовить решение для сбора данных, необходимых для вызова платёжной формы. Минимальный набор таких данных для проведения оплаты содержит идентификаторы проекта, платежа и пользователя, а также сумму и код валюты платежа.
    • Если выбран способ открытия Payment Page в модальном окне или в элементе iframe HTML-страницы — подключить CSS-библиотеку (https://paymentpage.ecommpay.com/shared/merchant.css), добавив её к странице веб-сервиса с помощью элемента <link>, который следует разместить внутри заголовка страницы.

      <head>
      ...
      <!-- Подключение CSS-библиотеки -->
      <link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" />
      ...
      </head>

      Это необходимо для корректного отображения платёжной формы при указанных способах открытия. Если же выбран способ открытия в отдельной вкладке браузера, подключение этих библиотек не требуется.

    • Если выбран способ открытия Payment Page в модальном окне и необходимо оформление модального окна в соответствии с дизайном веб-сервиса — определить стили CSS-классов для этого оформления (подробнее). При использовании способов открытия в элементе iframe и в отдельной вкладке браузера такое оформление не используется.
    • Реализовать отправку собранных данных в серверную часть веб-сервиса для их подписывания и обеспечить приём подписанных данных от серверной части.
    • Реализовать возможности вызова Payment Page выбранными способами: в отдельной вкладке браузера, в модальном окне и (или) в элементе iframe HTML-страницы.
    • Если необходимо фиксировать определённые интерфейсные события — открывать Payment Page в модальном окне или в элементе iframe HTML-страницы и реализовать функции для обработки таких событий.
  2. На стороне серверной части веб-сервиса:
    • Обеспечить приём данных для подписывания от клиентской части веб-сервиса.
    • Реализовать алгоритм формирования подписи данных.
    • Обеспечить отправку подписанных данных в клиентскую часть веб-сервиса.
    • Обеспечить приём оповещений от платёжной платформы, с проверкой подписи и отправкой ответов о приёме, а также обработку информации из этих оповещений.

Использование JavaScript-библиотеки

JavaScript-библиотека ECommPay подключается к клиентской части веб-сервиса и позволяет открывать Payment Page в модальном окне и в элементе iframe HTML-страницы. Кроме того, использование такой библиотеки позволяет отслеживать информацию об интерфейсных событиях в платёжной форме: выборе платёжного метода, изменении значений полей ввода и других (подробнее).

Если используется JavaScript-библиотека, на стороне серверной части могут использоваться как собственные решения, так SDK веб-сервисов. А на стороне клиентской части необходимо:

  • Подготовить решение для сбора данных, необходимых для вызова платёжной формы. Минимальный набор таких данных для проведения оплаты содержит идентификаторы проекта, платежа и пользователя, а также сумму и код валюты платежа.
  • Подключить CSS- и JavaScript-библиотеки (https://paymentpage.ecommpay.com/shared/merchant.css и https://paymentpage.ecommpay.com/shared/merchant.js), добавив к странице веб-сервиса с помощью элементов <link> для CSS-библиотеки и <script> для JavaScript-библиотеки. Эти элементы следует разместить внутри заголовка страницы.

    <head>
    ...
    <!-- Подключение CSS-библиотеки -->
    <link rel="stylesheet" href="https://paymentpage.ecommpay.com/shared/merchant.css" /> 
    <!-- Подключение JavaScript-библиотеки -->
    <script type="text/javascript" src="https://paymentpage.ecommpay.com/shared/merchant.js">
    </script>
    ...
    </head>
  • Если выбран способ открытия Payment Page в модальном окне и необходимо оформление модального окна в соответствии с дизайном веб-сервиса — определить стили CSS-классов для этого оформления (подробнее). При использовании способов открытия в элементе iframe и в отдельной вкладке браузера такое оформление не используется.
  • Реализовать отправку собранных данных в серверную часть веб-сервиса для их подписывания и обеспечить приём подписанных данных от серверной части.
  • Реализовать возможности вызова Payment Page по щелчку кнопки или по иному событию в пользовательском интерфейсе выбранным способом: в модальном окне или в элементе iframe HTML-страницы — с использованием JavaScript-объекта EPayWidget.
  • Если необходимо фиксировать определённые интерфейсные события — открывать Payment Page в модальном окне или в элементе iframe HTML-страницы и реализовать функции для обработки таких событий.

Использование SDK для веб-сервисов

SDK для веб-сервисов встраиваются в серверную часть веб-сервиса и позволяют осуществлять формирование подписи к запросам и обрабатывать оповещения. Если используются эти SDK, на стороне клиентской части могут использоваться как собственные решения, так и библиотека JavaScript и SDK для мобильных приложений. А на стороне серверной части необходимо обеспечить:

  • Приём запросов от клиентской части веб-сервиса.
  • Формирование подписи с использованием библиотек из состава SDK.
  • Отправку подписанного набора параметров в клиентскую часть веб-сервиса.
  • Приём оповещений и отправку ответов о приёме, а также использовать методы, доступные для работы с оповещениями при использовании SDK для веб-сервисов.

Подробная информация о подключении и использовании всех доступных SDK представлена в разделе Интеграция с использованием SDK.

Использование SDK для мобильных приложений

SDK для мобильных приложений встраиваются в клиентскую часть приложения и позволяют работать с платёжной формой, адаптированной под мобильные интерфейсы. Если используются эти SDK, на стороне серверной части могут использоваться как собственные решения, так и SDK для веб-сервисов. А на стороне клиентской части необходимо:

  • Подготовить страницу веб-сервиса для сбора данных, необходимых для вызова платёжной формы. Минимальный набор данных, который необходимо собрать для проведения оплаты, состоит из идентификаторов проекта, платежа и пользователя, а также суммы и валюты платежа.
  • Обеспечить выполнение других необходимых действий с использованием необходимых библиотек из состава SDK.

Подробная информация о подключении и использовании всех доступных SDK представлена в разделе Интеграция с использованием SDK.

Использование плагина для CMS

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

Информация о подключении и использовании плагинов для веб-сервисов, созданных на базе ряда CMS, представлена разделе Интеграция через CMS.

Порядок работы с запросами

Взаимодействие между веб-сервисом и Payment Page начинается с отправки запроса на открытие Payment Page для выполнения целевого действия. При получении такого запроса в платёжной платформе выполняются следующие действия:

  • На этапе приёма запроса обеспечивается проверка наличия минимального набора параметров и корректности подписи.
    • Если данные корректны, то запрос переводится на этап обработки и отправляется ответ о приёме запроса в обработку.
    • Если обнаружены ошибки, то работа с запросом прекращается и пользователю отображается информация об ошибке. При этом оповещение к веб-сервису не направляется.
  • На этапе обработки запроса сначала на стороне платёжной платформы выполняется подготовка Payment Page согласно настройкам проекта и параметрам вызова, а затем выполняется взаимодействие с пользователем с применением интерфейса платёжной формы.
    • Если пользователь подтверждает выполнение целевого действия, то запрос переводится на этап выполнения. Для всех целевых действий, за исключением формирования токена, на этом этапе в платформе регистрируется платёж: создаётся объект payment.
    • Если пользователь не подтверждает выполнение целевого действия, то работа с запросом прекращается. В этом случае не регистрируется платёж и не отправляется оповещение к веб-сервису.
  • На этапе выполнения запроса обеспечивается выполнение всех необходимых действий для получения целевого результата.
    • Если запрос выполнен, то к веб-сервису направляется оповещение о результате.
    • Если при выполнении запроса возникла ошибка, то работа с запросом прекращается и к веб-сервису направляется оповещение с информацией об этой ошибке.

Формат запроса

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

При работе с Payment Page все данные от веб-сервиса должны передаваться в запросах — HTTP-сообщениях заданной структуры. При этом формат данных и параметры адресации таких запросов зависят от выбранного способа открытия платёжной формы.

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

Методы отправки

Вне зависимости от выбранного способа открытия Payment Page для отправки HTTP-запросов поддерживаются методы POST и GET. Выбор метода осуществляется на стороне веб-сервиса и не ограничивается со стороны платёжной платформы. По умолчанию, если в HTTP-запросе не указано другое, запросы идентифицируются как отправленные методом GET. Однако в связи с тем, что в некоторых браузерах максимальная длина URL может ограничиваться, при передаче таких сведений, как информация о товарных позициях или «длинная запись», рекомендуется использовать метод POST.

Основные характеристики методов POST и GET представлены далее.

  POST GET
Уровень безопасности Более высокий за счёт передачи параметров в теле запроса Менее высокий в связи с передачей параметров в адресной строке
Возможность передачи всех параметров Payment Page API + *
Возможность передавать в виде ссылки +

* Ограничение объёма передаваемых данных допустимой длиной URL.

Рис.: Пример GET-запроса на открытие Payment Page

GET /payment?payment_currency=EUR&project_id=42&payment_amount=1000&customer_id=123&payment_id=4438&signature=AE5hmtzdP0Dt7qGTg... HTTP/1.1
Host: https://paymentpage.ecommpay.com

Рис.: Пример POST-запроса на открытие Payment Page

POST /payment HTTP/1.1
Host: https://paymentpage.ecommpay.com

{
  "payment_currency": EUR,
  "project_id": 42,
  "payment_amount": 1000,
  "customer_id": 123,
  "payment_id": "4438",
  "signature": "AE5hmtzdP0Dt7qGTg..."
}  

Параметры адресации

При формировании запросов на открытие Payment Page в отдельной вкладке браузера адреса отправки указываются следующим образом:

  • Если используется метод GET отправки запросов, в качестве доменного имени запрашиваемого ресурса необходимо указывать базовый адрес Payment Page (https://paymentpage.ecommpay.com), а в качестве целевого адреса — URL, используемый для выполнения целевых действий через Payment Page, знак вопроса ? и строку данных, состоящую из пар названий и значений параметров. Названия и значения разделяются знаками =, а сами пары разделяются знаками &.

    // URL, используемый для выполнения целевых действий через Payment Page
    /payment
    
    // Строка данных
    payment_currency=EUR&project_id=42&payment_amount=1000&customer_id=123&payment_id=4438&signature=AE5hmtzdP0Dt7qGTg%3D%3D
    
    // Полный адрес
    https://paymentpage.ecommpay.com/payment?payment_currency=EUR&project_id=42&payment_amount=1000&customer_id=123&payment_id=4438&signature=AE5hmtzdP0Dt7qGTg%3D%3D
  • Если используется метод POST отправки запросов, в качестве доменного имени запрашиваемого ресурса необходимо указывать базовый адрес Payment Page (https://paymentpage.ecommpay.com), а в качестве целевого адреса — URL, используемый для выполнения целевых действий через Payment Page. Данные в этом случае передаются в теле запроса.

При формировании запросов на открытие Payment Page в элементе iframe или в модальном окне, как правило, адреса отправки указывать не требуется.

Формат ответа

Со стороны Payment Page получение запроса подтверждается отправкой к пользовательскому браузеру ответа — HTTP-сообщения заданной структуры — в рамках того же сеанса. Передаваемые в ответе данные включают в себя:

  • сведения о приёме запроса, если запрос принят в обработку;
  • сведения об ошибке, если запрос не может быть принят в обработку.

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

Код с пояснением Описание
200 OK

Запрос успешно принят, можно ожидать итоговое оповещение.

Пользователю отображается платёжная форма

400 Bad Request

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

Пользователю отображается сообщение об ошибке

404 Not Found

Запрос не может быть обработан из-за некорректно указанных project_id или urlBase.

Пользователю отображается сообщение об ошибке

500 Internal Error

Запрос не может быть обработан из-за сбоя в платёжной платформе.

Пользователю отображается сообщение об ошибке

Формат оповещения

Для передачи промежуточной и итоговой информации о результате обработки и выполнения запроса в рамках асинхронного взаимодействия используются оповещения — HTTP-запросы, отправляемые методом POST от платёжной платформы на согласованные адреса. Общая структура оповещений описана далее, а подробная информация о работе с ними — в разделе Оповещения.

В каждом оповещении от платформы содержатся следующие элементы в порядке перечисления:

  • стартовая строка с указанием метода передачи запроса (POST), URL веб-сервиса для отправки оповещений о результатах (в примере — /notify/success), протокола и его версии (HTTP/1.1);
  • поля заголовка, в том числе поле Host с указанием доменного имени веб-сервиса (в примере — webservice.com);
  • пустая строка — разделитель, отделяющая служебную информацию от тела сообщения;
  • тело сообщения, содержащее JSON-строку в кодировке UTF-8 с набором данных и подписью к ним.

Далее представлен пример оповещения с информацией о результате проведения платежа. Содержимое JSON-строки в этом примере разбито на несколько строк для удобства чтения.

Рис.: Пример оповещения

POST /notify/success HTTP/1.1
Content-Length: 1237
User-Agent: GuzzleHttp/6.3.3 curl/7.47.0 PHP/7.0.32-0ubuntu0.16.04.1
Content-Type: application/json
Host: webservice.com

{
  "account":{
    "number":"421234******1234",
    "token":"1234567890",
    "type":"visa",
    "card_holder":"TEST TEST",
    "id":1234,
    "expiry_month":"**",
    "expiry_year":"****"
  },
  "customer":{
    "id":"12345",
    "phone":"***********"
  },
  "payment":{
    "date":"2019-06-07T11:38:31+0000",
    "id":"1234567890",
    "method":"card",
    "status":"success",
    "sum":{
      "amount":175000,
      "currency":"RUB"
    },
    "type":"purchase",
    "description":"Deposit to 1234567890"
  },
  "project_id":25,
  "processingDateTime":"2019-06-07T11:38:30+0000",
  "country":"RU",
  "product_name":"Visa",
  "issuer_name":"",
  "operation":{
    "id":1234567890,
    "type":"sale",
    "status":"success",
    "date":"2019-06-07T11:38:32+0000",
    "created_date":"2019-06-07T11:37:56+0000",
    "request_id":"1234567890-1234567890",
    "sum_initial":{
      "amount":175000,
      "currency":"RUB"
    },
    "sum_converted":{
      "amount":175000,
      "currency":"RUB"
    },
    "provider":{
      "id":11,
      "payment_id":"098765432",
      "date":"2019-06-07T11:38:30+0000",
      "auth_code":"",
      "endpoint_id":1
    },
    "code":"0",
    "message":"Success",
    "eci":"05"
  },
  "signature":"qwertyuioiuytrewqwertyuu123434"
}