Общий порядок интеграции

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

До начала работы с Payment Page вам нужно в своем веб-сервисе реализовать:

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

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

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

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

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

   • Если выбран способ открытия Payment Page в модальном окне или в элементе iframe HTML-страницы — подключить CSS-библиотеку, добавив ее на страницу веб-сервиса с помощью элемента <link>, который следует разместить внутри заголовка страницы.

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

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

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

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

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

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

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

• Подключить CSS- и JavaScript-библиотеки, добавив к странице веб-сервиса с помощью элементов <link> для CSS-библиотеки и <script> для JavaScript-библиотеки. Эти элементы следует разместить внутри заголовка страницы.

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

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

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

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

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

При работе с Payment Page все данные от веб-сервиса должны передаваться в запросах (requests) — 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.rocketpay.kz

POST /payment HTTP/1.1
Host: https://paymentpage.rocketpay.kz

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

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

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

• Если для отправки запросов используется метод GET, в качестве доменного имени запрашиваемого ресурса указывается базовый адрес Payment Page (например, https://paymentpage.rocketpay.kz), а затем следуют: URL-путь для выполнения целевых действий через Payment Page, знак вопроса ? и строка данных, состоящая из пар «имя-значение» параметра. Имена и значения параметров разделяются знаком «равно» (=), а сами пары разделяются знаками «амперсанд» (&). Информацию об URL-адресе Payment Page можно получить у своего курирующего менеджера Rocketpay.

  // 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.rocketpay.kz/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.example.com), а затем добавляют URL-путь для выполнения нужного действия через Payment Page. Данные в этом случае передаются в теле запроса. Базовый адрес Payment Page узнавайте у своего курирующего менеджера Rocketpay.

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

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

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

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

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

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

• стартовая строка с указанием метода передачи запроса (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"
}