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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

При возникновении вопросов о работе через Payment Page можно обращаться к курирующему менеджеру и специалистам технической поддержки Openpayze (support@openpayze.com).

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

JavaScript-библиотека Openpayze подключается к клиентской части веб-сервиса и позволяет открывать Payment Page в модальном окне и в элементе iframe HTML-страницы.

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

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

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

  <head>
  ...
  <!-- Подключение CSS-библиотеки -->
  <link rel="stylesheet" href="https://paymentpage.openpayze.com/shared/merchant.css" /> 
  <!-- Подключение JavaScript-библиотеки -->
  <script type="text/javascript" src="https://paymentpage.openpayze.com/shared/merchant.js">
  </script>
  ...
  </head>

• Реализовать отправку собранных данных в серверную часть веб-сервиса для их подписывания и обеспечить приём подписанных данных от серверной части.
• Реализовать возможности вызова Payment Page по щелчку кнопки или по иному событию в пользовательском интерфейсе выбранным способом: в модальном окне или в элементе iframe HTML-страницы — с использованием JavaScript-объекта EPayWidget.

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

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

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

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

Взаимодействие между веб-сервисом и 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.openpayze.com

POST /payment HTTP/1.1
Host: https://paymentpage.openpayze.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.openpayze.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.openpayze.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.openpayze.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

{
  "project_id": 200,
  "payment": {
    "id": "abc12345",
    "type": "purchase",
    "status": "success",
    "date": "2025-03-20T14:22:06+0000",
    "method": "Greek Banks",
    "sum": {
      "amount": 1000,
      "currency": "EUR"
    },
    "description": "Success"
  },
  "customer": {
    "id": "123"
  },
  "operation": {
    "id": 9529253065607,
    "type": "sale",
    "status": "success",
    "date": "2025-03-20T14:22:06+0000",
    "created_date": "2025-03-20T14:22:00+0000",
    "request_id": "f1de353331a01fd14163fe4226-00009530",
    "sum_initial": {
      "amount": 1000,
      "currency": "EUR"
    },
    "sum_converted": {
      "amount": 1000,
      "currency": "EUR"
    },
    "code": "0",
    "message": "Success",
    "provider": {
      "id": 1914,
      "payment_id": "",
      "auth_code": ""
    }
  },
  "signature": "OBjT3RaJnOWsDXOclvWoC6+CFSCtLprTo8VFbN6BYVQD2tVK/3d9k+RRA/7N9TV6OQqk+0uPUnx4/c8uaUurw=="
}