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

Платёжная форма 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, Yandex Browser, QQ, MIUI, Samsung Internet, 360 и ряда других.

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

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

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

   1. Если у компании нет идентификатора проекта и секретного ключа для взаимодействия с ecommpay — отправить заявку на подключение.
   2. Если планируется проводить платежи с использованием карт платёжных систем Visa и Mastercard — предоставить курирующему менеджеру ecommpay документы о соответствии требованиям PCI DSS:
      • Для всех мерчантов — отчёт о результатах ASV-сканирования.

        Такие сканирования должны выполняться авторизованными поставщиками (PCI SSC Approved Scanning Vendor, ASV) ежеквартально, а также после каждого значительного изменения сетевой инфраструктуры. Мерчанты ecommpay могут выбирать таких поставщиков самостоятельно и, если это актуально, могут задействовать поставщика, являющегося партнёром ecommpay. Чтобы организовать сканирования через партнёра ecommpay, можно обращаться к курирующему менеджеру.

      • Для мерчантов с количеством операций более 6 миллионов в год (уровня 1) — аттестат соответствия (Attestation of Compliance, AOC).
      • Для мерчантов с количеством операций до 6 миллионов в год (уровней 2, 3 и 4) — опросный лист (Self-Assessment Questionnaire, SAQ).

        С вопросами о правилах заполнения опросных листов можно обращаться к курирующему менеджеру ecommpay.

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

2. Выполнить подготовительные технические работы, собственными средствами или с использованием специализированных компонентов, предоставляемых ecommpay:

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

3. Совместно со специалистами технической поддержки ecommpay протестировать выполнение целевых действий и запустить решение по взаимодействию веб-сервиса с платёжной платформой в работу.

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

При возникновении вопросов о работе через Payment Page можно обращаться к курирующему менеджеру и специалистам технической поддержки 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 выбранными способами: в отдельной вкладке браузера, в модальном окне и (или) в элементе 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 по щелчку кнопки или по иному событию в пользовательском интерфейсе выбранным способом: в модальном окне или в элементе 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, представлена разделе Интеграция с использованием плагинов.

Взаимодействие между веб-сервисом и 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":"431422******0056",
    "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":17500,
      "currency":"EUR"
    },
    "type":"purchase",
    "description":"Deposit to 1234567890"
  },
  "project_id":25,
  "processingDateTime":"2019-06-07T11:38:30+0000",
  "country":"BE",
  "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":17500,
      "currency":"EUR"
    },
    "sum_converted":{
      "amount":17500,
      "currency":"EUR"
    },
    "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"
}