Организация взаимодействия
Общая информация
Платёжная форма 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 необходимо:
-
Решить организационные вопросы, касающиеся взаимодействия с ECommPay:
- Если у компании нет идентификатора проекта и секретного ключа для взаимодействия с ECommPay — отправить заявку на подключение.
- Для проведения платежей с использованием платёжных карт — предоставить курирующему менеджеру ECommPay копию сертификата или лист самооценки соответствия требованиям PCI DSS. С вопросами о заполнении листа самооценки можно обращаться к курирующему менеджеру ECommPay.
- При необходимости поддержать индивидуальный дизайн платёжной формы — согласовать с курирующим менеджером ECommPay условия реализации такого дизайна и необходимость проведения приёмки результатов.
- Согласовать со специалистами технической поддержки ECommPay порядок и сроки интеграции, тестирования и запуска в работу. В рамках согласования порядка тестирования могут быть согласованы возможности проведения тестовых платежей с использованием платёжных карт, а также некоторых из альтернативных методов.
-
Выполнить подготовительные технические работы, собственными средствами или с использованием специализированных компонентов, предоставляемых ECommPay:
- Если требуется индивидуальный дизайн платёжной формы — разработать макет в соответствии с требованиями, перечисленными в разделе Индивидуальный дизайн, и согласовать его со специалистами технической поддержки.
- Установить и подключить необходимые библиотеки и (или) плагины.
- Обеспечить возможности сбора параметров, необходимых для выполнения целевого действия, а также формирования и отправки запросов на открытие Payment Page на стороне клиентской части веб-сервиса.
- Обеспечить подписывание данных и корректное реагирование на оповещения на стороне серверной части веб-сервиса.
-
Совместно со специалистами технической поддержки 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.
Порядок взаимодействия между этими и другими сторонами представлен далее на схеме.
Рис.: Порядок взаимодействия
- Пользователь на стороне клиентской части веб-сервиса инициирует выполнение целевого действия.
- На стороне клиентской части веб-сервиса выполняется сбор параметров, необходимых для формирования запроса на открытие Payment Page, и их передача в серверную часть веб-сервиса.
- На стороне серверной части веб-сервиса выполняется обработка поступившего запроса:
- проверка параметров;
- дополнение полученных параметров хранящейся на стороне серверной части информацией, если это необходимо;
- формирование подписи к набору параметров.
- От серверной части веб-сервиса к его клиентской части направляется ответ на запрос.
- На стороне клиентской части выполняется приём ответа, а затем формирование и отправка на заданный URL ECommPay запроса на открытие Payment Page.
- Запрос на открытие Payment Page поступает в платёжную платформу.
- В платёжной платформе выполняется начальная обработка запроса, в рамках которой обеспечивается проверка наличия обязательных параметров и корректной подписи.
- Осуществляется подготовка Payment Page согласно настройкам проекта и параметрам вызова.
- Пользователю отображается подготовленная платёжная форма.
- Пользователь выполняет необходимые действия.
- Запрос на проведение платежа поступает в платёжную платформу.
- Выполняются дальнейшая обработка запроса и его отправка в платёжную среду.
- На стороне платёжной среды выполняется обработка платежа.
- От платёжной среды к платёжной платформе направляется уведомление о результате платежа.
- От платёжной платформы к веб-сервису направляется оповещение о результате платежа.
- От платёжной платформы к Payment Page направляется информация о результате проведения платежа.
- Результат платежа отображается пользователю на Payment Page.
Настройка веб-сервиса
Общая информация
Для начала работы с Payment Page на стороне веб-сервиса должны быть обеспечены:
- сбор параметров, необходимых для проведения платежа;
- формирование подписи;
- открытие Payment Page;
- обработка оповещений;
- корректное реагирование на оповещения с отправкой ответов об их приёме.
Для этого можно использовать как только собственные решения, так и специализированные компоненты, предоставляемые ECommPay: подключаемую JavaScript-библиотеку, SDK для проектов на разных языках программирования и подключаемые модули для сайтов на базе ряда распространённых CMS. Использование таких компонентов помогает полностью или частично снять необходимость в задействовании собственных решений.
С помощью компонентов, предоставляемых ECommPay, могут выполняться следующие действия:
JavaScript-библиотека | SDK для веб-сервисов | SDK для мобильных приложений | Плагины для CMS | |
|
– | – | + | + |
|
– | + | – | + |
|
+ | – | + | + |
|
– | + | – | + |
|
– | – | – | + |
Информация о настройке веб-сервиса с использованием собственных решений и каждого из специализированных компонентов, предоставляемых ECommPay, представлена далее.
Использование собственных решений
Для настройки взаимодействия с Payment Page с использованием собственных решений на стороне веб-сервиса необходимо обеспечить выполнение всех требуемых действий в клиентской и серверной частях.
- На стороне клиентской части веб-сервиса:
- Подготовить решение для сбора данных, необходимых для вызова платёжной формы. Минимальный набор таких данных для проведения оплаты содержит идентификаторы проекта, платежа и пользователя, а также сумму и код валюты платежа.
-
Если выбран способ открытия 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-страницы и реализовать функции для обработки таких событий.
- На стороне серверной части веб-сервиса:
- Обеспечить приём данных для подписывания от клиентской части веб-сервиса.
- Реализовать алгоритм формирования подписи данных.
- Обеспечить отправку подписанных данных в клиентскую часть веб-сервиса.
- Обеспечить приём оповещений от платёжной платформы, с проверкой подписи и отправкой ответов о приёме, а также обработку информации из этих оповещений.
Использование 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 |
Запрос не может быть обработан из-за некорректно указанных Пользователю отображается сообщение об ошибке |
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" }