Документация Clouden
Документация
/
Документация Clouden
/
Разработчику
/
Создание модулей
/
Создание модулей платежных систем
/
Создание модулей платежных систем
Добавить в избранное
Режим фокусировки
Документация
/
Документация Clouden
/
Разработчику
/
Создание модулей
/
Создание модулей платежных систем
/
Создание модулей платежных систем

Создание модулей платежных систем

Модуль платёжной системы отвечает за:

  • набор настроек подключения;
  • внешний вид формы настроек;
  • внешний вид и поведение формы оплаты на стороне клиента.

Также в модуле оплаты реализуются механизмы выставления, проведения и зачисления платежа от клиента. В зависимости от потребностей в модуле может быть реализована различная логика поведения при совершении оплаты — переадресация клиента на сайт платёжной системы для совершения оплаты или выставление счёта и ожидание, когда клиент проведёт оплату.

Механизм работы модуля

Жизненный цикл модуля оплаты в Clouden:

  1. Установка модуля.
  2. Добавление подключения к платёжной системе.
  3. Создание клиентом платежа.
  4. Оплата клиентом выставленного счёта.
  5. Зачисление или отмена платежа.

Установите модуль:

  • вручную, если он представлен набором файлов;
  • из стандартного репозитория при помощи пакетного менеджера.

После установки модуль становится доступен для выбора при создании метода оплаты в Clouden.

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

Структура модуля

Модуль платёжной системы состоит из двух и более файлов. Основные файлы — XML-описание модуля и скрипт, который передаёт конфигурацию модуля в платформу. Обычно используют два CGI-скрипта: для переадресации клиента на сайт платёжной системы и для получения оповещений об изменении статуса платежа от платёжной системы.

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

Стандартный список файлов модуля выглядит следующим образом (пути указаны относительно каталога установки Clouden):

  • etc/xml/billmgr_mod_pmXXX.xml — XML-описание модуля. Формат наименования файла строго регламентирован;
  • paymethods/pmXXX — основной скрипт модуля. Формат наименования файла строго регламентирован;
  • cgi/XXXpayment — скрипт оплаты, необязательный файл, наименование не регламентировано;
  • cgi/XXXresult — скрипт обработки оповещений, необязательный файл, наименование не регламентировано;
  • cgi/XXXrecurring — скрипт активации рекуррентной оплаты, необязательный файл, наименование не регламентировано;
  • cgi/XXXrecurringresult — скрипт обработки оповещений о рекуррентной оплате, необязательный файл, наименование не регламентировано.

Где XXX — название модуля, которое указывается латиницей. Если название основного скрипта модуля содержит расширение файла, оно также включается в имя модуля. Например, если ваш скрипт называется pmpay.php, то имя модуля — pay.php, а не pay.

Описание XML

Наименование файла должно иметь вид billmgr_mod_pmXXX.xml, где XXX — имя модуля. Файл копируется в каталог /etc/xml относительно пути установки Clouden. Файл содержит описание самого модуля (описывается как плагин), а также описание дополнительных форм и сообщений.

Пример XML-файла

Здесь элемент <plugin> отвечает за описание самого модуля. Свойство name совпадает с именем модуля оплаты. Внутри элемента может быть один элемент group со значением payment_method, который указывает, что данный модуль используется для методов оплаты, и несколько элементов msg. Свойство lang у элемента указывает, к какому языку относится сообщение, атрибут name может иметь следующие значения:

  • desc_short — краткое описание модуля. Отображается при выборе модуля оплаты в Clouden;
  • desc_full — полное описание модуля. Отображается при построении списка установленных модулей в COREmanager.

Элемент metadata с именем paymethod.edit.XXX отвечает за дополнительные поля модуля при добавлении и настройке метода оплаты. Формируется согласно стандартному описанию XML-формы. Разместите поля в элементе <page name="methodprops"></page> для корректного размещения полей на формах в Clouden. Единственным отличием от стандартного описания является поддержка атрибута private, который запрещает вывод данного атрибута в XML при печати счёта по созданному платежу. Используется для секретных данных, таких как пароль или секретный ключ. Элементы page с именами recurring и refundpage описывают настройки рекуррентных платежей и настройки отмены платежей, соответственно.

Элемент metadata с именем payment.edit.XXX отвечает за дополнительные поля, которые клиент видит при совершении оплаты. Также описывается согласно стандартной схеме для XML-форм в Clouden.

Элемент metadata с именем paymethod.transfer.XXX отвечает за дополнительные поля, отображаемые при переводе средств обратно клиенту. Также описывается согласно стандартной схеме описания XML-форм в Clouden.

Элемент lang содержит переводы наименований полей на форме согласно стандартной схеме описания переводов. Раздел <messages name="label_paymethod"> отвечает за подпись наименования модуля в списке методов оплаты.

Основной скрипт модуля

Основной скрипт модуля оплаты отвечает за передачу Clouden информации о поддерживаемых модулем функциях, а также обработку некоторых из этих функций. При работе с модулем Clouden исполняет файл скрипта со следующими параметрами:

paymethods/pmxxx --command cmd [--payment id [--amount amnt]]

Где:

  • cmd — управляющая команда;
  • id — код платежа;
  • amnt — сумма в валюте метода оплаты (используется при возврате и переводе денежных средств).

В параметр --command могут быть переданы следующие значения:

  • config — запрос конфигурации модуля. В ответ модуль должен вернуть в стандартный поток вывода XML-документ:
    Пример XML-документа

Элемент feature содержит список возможностей модуля оплаты. Если возможность не поддерживается, она не должна присутствовать в выводе результата выполнения команды.

Список допустимых значений:

  • refund — указывает на поддержку отмены платежей, возврата средств. Без этой возможности обработка команд rftune, rfvalidate, rfset не требуется;
  • transfer — указывает на поддержку перевода средств со счёта в платёжной системе на счёт клиента. Без этой возможности обработка команд tftune, tfvalidate, tfset не требуется;
  • recurring — указывает на поддержку рекуррентных платежей. Без этой возможности параметры recurring_script и recurring_type можно не указывать;
  • redirect — указывает, что для совершения оплаты с помощью модуль переадресует клиента в платёжную систему;
  • noselect — метод оплаты не будет отображаться в списке при выборе клиентом. Используется в случае, если для оплаты не требуется предварительное создание платежа в Clouden. Например, при оплате через терминал;
  • notneedprofile — указывается, если для совершения платежа указание плательщика не обязательно. Однако, если метод оплаты будет подключён к компании, система запросит у клиента создание или выбор плательщика;
  • pmtune — указывает, если для корректного отображения формы настройки метода оплаты нужно выполнить дополнительные действия. Подробнее см. в описании команды pmtune;
  • pmvalidate — если указано, при сохранении параметров метода оплаты будет вызван модуль для проверки введённых значений;
  • crtune — указывается, если для корректного отображения формы оплаты требуется выполнение дополнительных действий. Подробнее см. в описании команды crtune;
  • crvalidate — если указан, при сохранении введённых клиентом значений будет вызван модуль для проверки введённых значений;
  • crset — указывается, если:
    • перед переадресацией на оплату требуется выполнение каких-либо действий модулем;
    • оплата совершается без перехода в платёжную систему;
    • при оплате необходим ввод данных клиентом;
  • crdelete — указывается, если для корректного удаления платежа необходимо выполнение действий на стороне платёжной системы;
  • rftune — аналогично crtune, но при возврате средств;
  • rfvalidate — аналогично crvalidate, но при возврате средств;
  • rfset — обязательная возможность для возврата средств. При вызове команды модуль выполняет все необходимые действия для возврата;
  • rctune — аналогично crtune, но при рекуррентных платежах;
  • rcvalidate — аналогично crvalidate, но при рекуррентных платежах;
  • rcset — аналогично crset, но при настройке рекуррентных платежей со стороны клиента. Используется для настройки рекуррентных платежей со стороны платёжной системы;
  • rcpay — вызывается при создании в Clouden рекуррентного платежа. Используется для вызова оплаты со стороны платёжной системы;
  • rcdelete — указывается, если для корректного удаления профиля автоплатежа необходимо выполнение действий на стороне платёжной системы;
  • tftune — аналогично crtune, но при переводе средств;
  • tfvalidate — аналогично crvalidate, но при переводе средств;
  • tfset — обязательная возможность для перевода средств. При вызове команды модуль выполняет все необходимые действия для перевода.

Элемент param содержит список параметров метода оплаты. Поддерживаются:

  • payment_script — путь к скрипту переадресации на оплату относительно домена установки Clouden. Например, если скрипт находится по адресу http://domain.com/cgi/pullpayment.php , укажите /mancgi/pullpayment.php
  • recurring_script — путь к скрипту переадресации на подтверждение активации рекуррентных платежей. Например, если скрипт находится по адресу http://domain.com/cgi/pullrecurringpayment.php , укажите /mancgi/pullrecurringpayment.php
  • recurring_type — битовая маска поддерживаемых возможностей рекуррентных платежей. Формируется путём установки соответствующих битов в единицу с помощью побитового сдвига влево и побитового ИЛИ. Перечисленные числа — это позиции битов, а не десятичные значения для арифметического сложения.  Доступные позиции битов:
    • 1 — платёж создаётся отдельно по каждой услуге;
    • 2 — платёж создаётся по нескольким услугам;
    • 7 — платёж создаётся по всем услугам;
    • 8 — для регистрации платежа требуется указание максимальной суммы;
    • 20 — для подтверждения рекуррентного платежа требуется переадресация в платёжную систему;
    • 21 — для подтверждения необходимо выполнение клиентом дополнительных действий.
    Пример
  • pmtune — вызывается для изменения формы настройки метода оплаты. На стандартный вход скрипту подаётся XML-форма настройки, на выход ожидается изменённая и дополненная XML-форма;
  • pmvalidate — вызывается для проверки введённых в настройках метода оплаты значений. На стандартный вход подаётся XML-документ, содержащий введённые на форме значения, на выход ожидается XML-документ, содержащий описание ошибок ввода, либо пустой XML-документ;
  • crtune — вызывается для изменения формы оплаты. На стандартный вход скрипту подаётся XML-форма оплаты, на выход ожидается изменённая и дополненная XML;
  • crvalidate — вызывается для проверки введённых при оплате значений. На стандартный вход подаётся XML-документ, содержащий введённые на форме значения, на выход ожидается XML-документ, содержащий описание ошибок ввода, либо пустой XML-документ;
  • crset — вызывается при нажатии Ок на форме оплаты. Параметром передаётся код платежа, по которому можно получить все необходимые данные. Платформа сохраняет введённые пользователем данные в базу;
  • crdelete — вызывается при нажатии Удалить в списке платежей. Параметром передаётся код платежа, который требуется удалить;
  • rftune — вызывается для изменения формы возврата средств. На стандартный вход скрипту подаётся XML-форма возврата, на выход ожидается изменённая и дополненная XML-форма;
  • rfvalidate — вызывается для проверки введённых при возврате значений. На стандартный вход подаётся XML-документ, содержащий введённые на форме значения, на выход ожидается XML-документ, содержащий описание ошибок ввода, либо пустой XML-документ;
  • rfset — вызывается при нажатии Ок на форме возврата. На стандартный ввод подаётся XML-документ, содержащий:
    • данные об исходном либо созданном для возврата платеже;
    • данные о сумме возврата;
    • описание причины возврата;
    • параметры метода оплаты;
  • tftune — вызывается для изменения формы перевода средств. На стандартный вход скрипту подаётся XML-форма перевода, на выход ожидается изменённая и дополненная XML-форма;
  • tfvalidate — вызывается для проверки введённых при переводе значений. На стандартный вход подаётся XML-документ, содержащий введённые на форме значения, на выход ожидается XML-документ, содержащий описание ошибок ввода, либо пустой XML-документ;
  • tfset — вызывается при нажатии Ок на форме перевода. На стандартный ввод подаётся XML-документ, содержащий данные о созданном для перевода платеже, сумму перевода, а также параметры метода оплаты;
  • rcdelete — вызывается при отключении автоплатежа. Параметром передаётся код профиля автоплатежа, который требуется удалить.

Пример реализации скрипта можно найти в конце статьи.

CGI-скрипты модуля

CGI-скрипты — необязательная часть модуля оплаты. Они могут отсутствовать, в случае, если вся логика реализована в основном модуле. Например, при оплате через WebMoney-кошелёк, счёт выставляется пользователю непосредственно основным скриптом модуля и его оплата проверяется по расписанию.

Возможны также случаи, когда модуль содержит несколько CGI-скриптов:

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

Например, для интеграции с ЮMoney реализован дополнительный CGI-скрипт, выполняющий проверку введённых клиентом данных на стороне ЮMoney. Для этого платёжная система вызывает скрипт и передаёт ему введённые клиентом данные, а также параметр, отвечающий за тип операции — check.

CGI-скрипты могут располагаться на отличном от Clouden сервере, либо на другом IP-адресе или домене. Все зависит от требований разработчика модуля и платёжной системы. Например, существуют схемы, при которых авторизация при отправке уведомления об изменении статуса платежа выполняется по клиентскому сертификату. В этом случае требуется размещение скрипта на отдельном VirtualHost с настройкой обработки клиентских сертификатов. Но чаще всего какая-либо специфика в интеграции отсутствует, и для упрощения поддержки модуля оплаты рекомендуется размещать CGI-скрипты в стандартном каталоге Clouden — /usr/local/mgr5/cgi

Для примера разберём скрипты следующих типов:

  • переадресации на оплату;
  • получения уведомлений об изменении статуса.

Скрипт переадресации на оплату

Адрес скрипта переадресации на оплату Clouden получает вместе с загрузкой данных модуля при первом обращении к нему. Чаще всего скрипт формирует форму с необходимыми параметрами и автоматически отправляет её.

Пример формы
<html>
  <head>
    <meta http-equiv='Content-Type' content='text/html; charset=UTF-8' />
    <link rel='shortcut icon' href='billmgr.ico' type='image/x-icon' />
    <script language='JavaScript'>
      function submit() {
        document.frm.submit();
      }
    </script>
  </head>
  <body onload='submit()'>
    <form name='frm' action='https://paysystem/url' method='post'>
      <input type='hidden' name='shop_id' value='1'>
      <input type='hidden' name='amount' value='1.00'>
    </form>
  </body>
</html>

В скрипт переадресации на оплату всегда передаётся параметр elid, содержащий код платежа. По значению этого параметра функции payment.info можно получить все данные, необходимые для формирования формы оплаты. Функция возвращает ответ в формате XML или JSON:

Подробнее

К элементу payment добавляются все параметры, которые нужно дополнительно указать клиентам при оплате. К элементу paymethod добавляются все параметры метода оплаты. Такой способ получения информации о платеже более предпочтителен, чем прямое обращение к базе данных Clouden.

Пример скрипта переадресации можно посмотреть в конце статьи.

Скрипт получения уведомлений об изменении состояния платежа

Скрипт обработки оповещений об изменении статуса платежа от платёжной системы выполняет следующие действия:

  1. Выделяет из полученных от платёжной системы данных код платежа в Clouden;
  2. По коду платежа получает информацию о платеже и параметрах метода оплаты:
    • из базы данных;
    • при помощи функции payment.info;
  3. Сравнивает данные, полученные от платёжной системы с данными, хранящимися в Clouden;
  4. При наличии у полученных данных контрольной подписи проверяет её с помощью секретного ключа;
  5. Изменяет статус платежа в Clouden в соответствии с полученными данными с помощью одной из функций, описанных ниже;
  6. При необходимости оповещает платёжную систему об успешной или неуспешной обработке входящего запроса.

Пример скрипта обработчика оповещений об оплате можно найти в конце статьи.

Функции Clouden

ФункцияОписаниеПараметры
payment.infoОтображает всю доступную информацию о платеже.
  • elid — код платежа.

payment.setfraud

Помечает платёж как мошеннический.
  • elid — код платежа;
  • info — дополнительная информация;
  • externalid — код платежа в платёжной системе.

payment.setinpay 

Помечает платёж как оплачиваемый.
  • elid — код платежа;
  • info — дополнительная информация;
  • externalid — код платежа в платёжной системе.

payment.setnopay

Помечает платёж как неоплаченный.
  • elid — код платежа;
  • info — дополнительная информация;
  • externalid — код платежа в платёжной системе.

payment.setpaid

Зачисляет платёж.
  • elid — код платежа;
  • info — дополнительная информация;
  • externalid — код платежа в платёжной системе.

payment.success

Отображает страницу успешного завершения оплаты.
  • elid — код платежа;
  • module — имя модуля интеграции.

payment.fail

Отображает страницу ошибки при оплате.
  • elid — код платежа;
  • module — имя модуля интеграции.

Страницы возврата

Для возврата клиента в биллинговую платформу после совершения оплаты можно использовать:

  • самостоятельно разработанные CGI-скрипты;
  • статические HTML-страницы;
  • стандартные функции Clouden.

Во всех случаях: 

  • payment.success — страница успешного завершения оплаты, где elid — код платежа;
  • payment.fail — страница ошибки оплаты, где elid — код платежа.

Чтобы дополнить формы, отображаемые функциями, укажите в XML-описании плагина:

Пример дополнения
<metadata name="payment.XXX.fail" type="form">
  <form>
    <field name="fail_description" noname="yes" formwidth="yes">
      <textdata name="fail_description"/>
    </field>
  </form>
</metadata>

 <metadata name="payment.XXX.success" type="form">
  <form> 
    <field name="success_description" noname="yes" formwidth="yes">
      <textdata name="success_description"/>
    </field>
  </form>
</metadata>

<lang name="en">
  <messages name="payment.XXX.fail">
    <msg name="fail_description">Fail</msg>
  </messages>
  <messages name="payment.XXX.success">
    <msg name="success_description">Success</msg>
  </messages>
</lang>
<lang name="ru">
  <messages name="payment.XXX.fail">
    <msg name="fail_description">Ошибка</msg>
  </messages>
  <messages name="payment.XXX.success">
    <msg name="success_description">Успех</msg>
  </messages>
</lang>

Пример модуля

Пример иллюстрирует реализацию модуля оплаты по PULL (REST) протоколу.

PHP

Модуль состоит из следующих основных файлов:

  • etc/xml/billmgr_mod_pmpull.php.xml — XML-описание;
  • paymethods/pmpull.php — основной скрипт;
  • cgi/pullpayment.php — CGI-скрипт перенаправления на оплату;
  • cgi/pullresult.php — CGI-скрипт получения уведомлений от платёжной системы.

А также вспомогательного файла:

  • include/php/bill_util.php

Функции bill_util.php

Перед включением в свой скрипт файла bill_util.php необходимо определить макрос __MODULE__, для формирования имени файла лога. 

Пример определения макроса __MODULE
set_include_path(get_include_path() . PATH_SEPARATOR . "/usr/local/mgr5/include/php"); 
define('__MODULE__', "pmXXX"); 
require_once 'bill_util.php';

Файл bill_util.php предоставляет следующие функции:

  • Debug($str) — выводит $str в качестве дополнительной информации в лог;
  • Error($str) — выводит $str в качестве сообщения об ошибке в лог;
  • LocalQuery($function, $param, $auth = NULL) — выполняет в Clouden функцию $function, передав ей параметры из массива $param и код сессии из $auth;
  • HttpQuery($url, $param, $requesttype = "POST", $username = "", $password = "", $header = array("Accept: application/xml")) — выполняет запрос к $url с параметрами из $param используя тип запроса $requesttype и данные авторизации из $username и $password. Также можно передать дополнительные заголовки в $header;
  • CgiInput($skip_auth = false) — получает массив параметров, полученных скриптом в строке запроса или POST-данных. Параметр $skip_auth отвечает за получение параметра auth из cookie, если он отсутствует в полученных данных;
  • ClientIp() — получает IP-адрес, с которого вызван скрипт;
  • class Error — определяет класс ошибки, имитирующей поведение при ошибках в COREmanager.

C++ (с использованием библиотек Clouden)

Использование заголовочных файлов Clouden для разработки собственных модулей обработчиков доступно с версии Clouden 5.58.0. Кроме приведённого примера, можно изучить примеры, представленные в пакете разработчика Clouden —  billmanager-[Редакция Clouden]-devel:

dnf install billmanager-corporate-devel
или
dnf install billmanager-devel
Пояснения

Примеры можно найти в директории /usr/local/mgr5/src/examples

С++

Пример модуля расположен по адресу https://github.com/ISPsystemLLC/interkassa. Модуль использует заголовочные файлы COREmanager и Clouden, и основан на примерах сборки собственных компонентов, описанных в статьях Сборка собственных компонентов и Взаимодействие на низком уровне, плагины с++.

Также при написании модулей могут быть полезны материалы из раздела Разработчику документации Clouden.

Структура модуля

Модуль состоит из обязательных файлов:

  • pminterkassa.cpp — код основного исполняемого файла модуля оплаты;
  • xml/billmgr_mod_pminterkassa.xml — XML-описание модуля.

Также в модуль входят CGI-скрипты:

  • скрипт переадресации на оплату в процессинговый центр;
  • скрипт приёма оповещений о зачислении платежей.