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

Платёжная форма 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.

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

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

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

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

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

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

Информация о настройке веб-сервиса с использованием собственных решений и каждого из специализированных компонентов, предоставляемых 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 представлены далее.

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

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 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-сообщения заданной структуры — в рамках того же сеанса. Передаваемые в ответе данные включают в себя:

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

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

Для передачи промежуточной и итоговой информации о результате обработки и выполнения запроса в рамках асинхронного взаимодействия используются оповещения — 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"
}