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

Платёжные методы интегрируют BILLmanager с внешними платёжными системами. Модуль платёжной системы отвечает за:

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

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

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

Общие сведения

Каталог установки: /usr/local/mgr5/paymethods/
XML-описание: /usr/local/mgr5/etc/xml/billmgr_mod_pm<имя>.xml

Управление: основной скрипт модуля (pmXXX) и CGI-скрипты.

Основной модуль pm<имя> вызывается только BILLmanager. У модуля нет данных о браузере пользователя, и он не возвращает HTML-код. Задачи модуля:

• сообщить BILLmanager о поддерживаемых возможностях (--command config);
• настроить и валидировать параметры метода оплаты (pmtune, pmvalidate);
• выполнить оплату без редиректа или произвести подготовительные действия перед редиректом (crset);
• проверить статус платежей ( checkpay);
• выполнить возврат или перевод средств (rfset, tfset).

CGI-скрипты вызываются из браузера пользователя или платёжной системой по HTTP. Они работают как обычные веб-страницы и могут выдавать HTML-код. Задачи CGI-скриптов:

• перенаправить пользователя на страницу оплаты платёжной системы (payment_script);
• принять уведомление (webhook) от платёжной системы об изменении статуса платежа и вызвать payment.setpaid (скрипт результата);
• показать страницу привязки карты для автоплатежей (recurring_script).

CGI-скрипты необязательны — если вся логика реализована в основном модуле (например, оплата по выставленному счёту без редиректа), они могут отсутствовать. Подробнее см. раздел CGI-скрипты модуля.

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

Этапы работы с модулем платёжной системы в BILLmanager:

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

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

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

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

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

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

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

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

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

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

Описание XML

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

<mgrdata>
  <plugin name="XXX">
    <group>payment_method</group>
    <msg name="desc_short" lang="ru">XXX модуль</msg>
    <msg name="desc_short" lang="en">XXX module</msg>
    <msg name="desc_full" lang="ru">XXX модуль</msg>
    <msg name="desc_full" lang="en">XXX module</msg>
  </plugin>

  <metadata name="paymethod.edit.XXX" type="form">
    <form>
      <page name="methodprops">
        <field name="prop1">
          <input name="prop1" required="yes" type="text" />
        </field>
        <field name="prop2">
          <input name="prop2" private="yes" required="yes" type="text" />
        </field>
      </page>
      <page name="recurring">
        <field name="recurring">
         <input type="checkbox" name="recurring">
           <if value="off" hide="recurringprop1"/>
           <if value="off" hide="recurringprop2"/>
         </input>
        </field>
        <field name="recurringprop1">
          <input name="recurringprop1" required="yes" type="text" />
        </field>
        <field name="recurringprop2">
          <input name="recurringprop2" private="yes" required="yes" type="text" />
        </field>
      </page>
      <page name="refundpage">
        <field name="allowrefund">
         <input type="checkbox" name="allowrefund">
           <if value="off" hide="refundprop1"/>
           <if value="off" hide="refundprop2"/>
         </input>
        </field>
        <field name="refundprop1">
          <input name="refundprop1" required="yes" type="text" />
        </field>
        <field name="refundprop2">
          <input name="refundprop2" private="yes" required="yes" type="text" />
        </field>
      </page>
    </form>
  </metadata>

  <metadata name="payment.edit.XXX" type="form">
    <form>
      <field name="payment_prop">
        <input type="text" name="payment_prop" required="yes"/>
      </field>
    </form>
  </metadata>

  <metadata name="paymethod.transfer.XXX" type="form">
    <form>
      <field name="param">
        <input type="text" name="param" required="yes"/>
      </field>
    </form>
  </metadata>

  <lang name="en">
    <messages name="label_paymethod">
      <msg name="pmXXX">XXX module</msg>
      <msg name="module_pmXXX">XXX module</msg>
    </messages>

    <messages name="paymethod.edit.XXX">
      <msg name="prop1">Prop 1</msg>
      <msg name="hint_prop1">Hint for prop 1</msg>
      <msg name="prop2">Prop 2</msg>
      <msg name="hint_prop2">Hint for prop 2</msg>

      <msg name="recurringprop1">Recurring prop 1</msg>
      <msg name="hint_recurringprop1">Hint for recurring prop 1</msg>
      <msg name="recurringprop2">Recurring prop 2</msg>
      <msg name="hint_recurringprop2">Hint for recurring prop 2</msg>

      <msg name="refundprop1">Refund prop 1</msg>
      <msg name="hint_refundprop1">Hint for refund prop 1</msg>
      <msg name="refundprop2">Refund prop 2</msg>
      <msg name="hint_refundprop2">Hint for refund prop 2</msg>
    </messages>

    <messages name="paymethod.transfer.XXX">
      <msg name="param">Param</msg>
      <msg name="hint_param">Hint param</msg>
    </messages>

    <messages name="payment.edit.XXX">
      <msg name="payment_prop">Prop</msg>
      <msg name="hint_payment_prop">Hint for prop</msg>
      <msg name="placeholder_payment_prop">prop</msg>
    </messages>
  </lang>

  <lang name="ru">
     <messages name="label_paymethod">
      <msg name="pmXXX">XXX модуль</msg>
      <msg name="module_pmXXX">XXX модуль</msg>
    </messages>

    <messages name="paymethod.edit.XXX">
      <msg name="prop1">Свойство 1</msg>
      <msg name="hint_prop1">Подсказка для свойства 1</msg>
      <msg name="prop2">Свойство 2</msg>
      <msg name="hint_prop2">Подсказка для свойства 2</msg>
    </messages>

    <messages name="paymethod.transfer.XXX">
      <msg name="param">Параметр</msg>
      <msg name="hint_param">Подсказка для параметра</msg>
    </messages>

    <messages name="payment.edit.XXX">
      <msg name="payment_prop">Свойство</msg>
      <msg name="hint_payment_prop">Подсказка для свойства</msg>
      <msg name="placeholder_payment_prop">свойство</msg>
    </messages>
  </lang>
</mgrdata>

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

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

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

Элемент metadata с именем payment.edit.XXX отвечает за дополнительные поля, которые клиент видит при совершении оплаты. Описывается согласно стандартной схеме для XML-форм в BILLmanager. Подробнее см. в статье Модули. Общие принципы.

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

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

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

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

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

Где:

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

Обязательная команда:

• config — возвращает XML-файл с <feature> (список поддерживаемых возможностей) и <param> (пути к CGI-скриптам или recurring).

Основные команды (вызываются в зависимости от заявленных <feature>):

• pmtune или pmvalidate — настройка и проверка параметров метода оплаты;
• crtune или crvalidate или crset — настройка формы оплаты, проверка данных, выполнение платежа;
• crdelete — удаление платежа;
• rftune или rfvalidate или rfset — настройка, проверка и выполнение возврата (refund);
• tftune или tfvalidate или tfset — настройка, проверка и выполнение перевода (transfer);
• rctune или rcvalidate или rcset или rcpay или rcdelete — рекуррентные (автоматические) платежи (recurring);
• checkpay — проверка статуса платежей.

Возможные <feature> в ответе config:

• refund;
• transfer;
• recurring;
• redirect;
• noselect;
• notneedprofile;
• pmtune;
• pmvalidate;
• crtune;
• crvalidate;
• crset;
• crdelete;
• rftune;
• rfvalidate;
• rfset;
• tftune;
• tfvalidate;
• tfset;
• rctune;
• rcvalidate;
• rcset;
• rcpay;
• rcdelete.

/usr/local/mgr5/paymethods/pmnowpayments --command config

Пояснения к XML-файлу

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

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

  Пример XML-документа

  <doc>
  	<feature>
  		<refund>on</refund>
  		<recurring>on</recurring>
  		<redirect>on</redirect>
  		<crset>on</crset>
  	</feature>
  	<param>
  		<payment_script>/mancgi/pullpayment.php</payment_script>
  		<recurring_script>/mancgi/pullrecurring.php</recurring_script>
  		<recurring_type>20</recurring_type>
  	</param>
  </doc>

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

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

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

BILLmanager передаёт пути к скриптам через ответ команды config в секции <param>. BILLmanager использует эти пути для формирования ссылок, по которым браузер пользователя или платёжная система будут обращаться к скриптам.

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

• payment_script — путь к скрипту переадресации на оплату относительно домена установки BILLmanager. Например, если скрипт находится по адресу http://domain.com/cgi/pullpayment.php , укажите /mancgi/pullpayment.php;
• recurring_script — путь к скрипту переадресации на подтверждение активации рекуррентных платежей. Например, если скрипт находится по адресу http://domain.com/cgi/pullrecurringpayment.php , укажите /mancgi/pullrecurringpayment.php;
• recurring_type — битовая маска поддерживаемых возможностей рекуррентных платежей. Каждому пункту ниже соответствует позиция бита: чтобы получить значение флага, нужно сдвинуть 1 влево на указанное количество позиций (1 << N). Итоговое значение параметра — результат объединения нужных флагов через побитовое ИЛИ. 
  • 1 (значение 2) — платёж создаётся отдельно по каждой услуге;
  • 2 (значение 4) — платёж создаётся по нескольким услугам;
  • 7 (значение 128) — платёж создаётся по всем услугам;
  • 8 (значение 256) — для регистрации платежа требуется указание максимальной суммы;
  • 20 (значение 1 048 576) — для подтверждения рекуррентного платежа требуется переадресация в платёжную систему;
  • 21 (значение 2 097 152) — для подтверждения необходимо выполнение клиентом дополнительных действий. 

• Пример

  Например, чтобы указать, что платёж создаётся отдельно по каждой услуге (позиция 1) и для подтверждения требуется переадресация (позиция 20), нужно сдвинуть единицу влево на 1 и на 20 бит, а затем объединить результаты побитовым ИЛИ:

  (1 << 1) | (1 << 20) = 2 | 1 048 576 = 1 048 578.

  Итоговое значение для параметра recurring_type в этом случае — 1 048 578.

*tune (pmtune, crtune, rftune, tftune, rctune) — вход и выход

Вход — стандартная XML-форма BILLmanager.
Выход — изменённый XML-файл формы.

*validate (pmvalidate, crvalidate, rfvalidate, tfvalidate, rcvalidate) — вход и выход

Вход: XML-форма с данными, введёнными пользователем на форме.

<doc>
<field1>value1</field1>
<field2>value2</field2>
</doc>

Выход: при успехе — <doc/>; при ошибке — XML-форма ошибки.

rfset — вход (stdin)

Принимает данные об исходном либо созданном для возврата платеже. Например:

• сумму возврата;
• описание причины возврата;
• параметры метода оплаты.

	<doc>
		<!-- Идентификатор платежа. -->
		<payment>100500</payment>

	<!-- Идентификатор способа оплаты. -->
	<paymethod>25</paymethod>

		<!-- Сумма возврата в валюте платёжного метода. -->
	<payment_paymethodamount>-250.00</payment_paymethodamount>

	<!-- Описание платежа. -->
	<payment_description>Возврат средств по заказу #12345</payment_description>

	<!-- Дополнительные параметры способа оплат. -->
	<paymethod_xmlparams>
		...
	</paymethod_xmlparams>

	<!-- Валюта платёжного метода. -->
	<paymethod_currency>RUB</paymethod_currency>

	<!-- Исходный платеж, по которому делается возврат или перевод. -->
	<source_payment>5001</source_payment>	

	<!-- Дополнительные пользовательские данные.-->
	<user_field>custom_value</user_field>
</doc>

tfset — вход (stdin)

Принимает данные о созданном для перевода платеже. Например:

• сумму перевода;
• параметры метода оплаты.

	<doc>
		<!-- Идентификатор платежа. -->
		<payment>100500</payment>

	<!-- Идентификатор способа оплаты. -->
	<paymethod>25</paymethod>

		<!-- Сумма возврата в валюте платёжного метода. -->
	<payment_paymethodamount>-250.00</payment_paymethodamount>

	<!-- Описание платежа. -->
	<payment_description>Возврат средств по заказу #12345</payment_description>

	<!-- Дополнительные параметры способа оплаты. -->
	<paymethod_xmlparams>
		...
	</paymethod_xmlparams>

	<!-- Валюта платёжного метода. -->
	<paymethod_currency>RUB</paymethod_currency>

	<!-- Исходный платеж, по которому делается перевод. -->
	<source_payment>5001</source_payment>	

	<!-- Дополнительные пользовательские данные.-->
	<user_field>custom_value</user_field>
</doc>

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

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

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

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

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

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

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

Скрипт оплаты (payment_script) получает через HTTP-запрос параметр elid (идентификатор платежа). С помощью функции payment.info скрипт запрашивает данные, необходимые для формирования формы оплаты. Стандартный способ — автоматическая отправка формы при загрузке страницы:

<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>

Функция возвращает ответ в формате XML или JSON:

<doc>
  <payment>                                                   <!-- Информация о платеже -->
    <id>1</id>                                                <!-- Код платежа -->
    <subaccount>1</subaccount>                                <!-- Код лицевого счёта клиента -->
    <paymethod>1</paymethod>                                  <!-- Код метода оплаты -->
    <recipient/>                                              <!-- Код компании-получателя платежа. При наличии данные компании также добавляются в вывод функции -->
    <sender/>                                                 <!-- Код плательщика, от имени которого совершается платёж. При наличии данные плательщика также добавляются в вывод функции -->
    <subaccountamount>1.00</subaccountamount>                 <!-- Сумма платежа в валюте счёта -->
    <status>2</status>                                        <!-- Статус платежа -->
    <number>pfx/1</number>                                    <!-- Номер платежа -->
    <paymethodamount>1.00</paymethodamount>                   <!-- Сумма платежа в валюте метода оплаты -->
    <currency>126</currency>                                  <!-- Код валюты суммы платежа -->
    <externalid/>                                             <!-- Внешний код платежа, может быть сохранён функцией payment.setpaid -->
    <description>Advanced payment</description>               <!-- Описание назначения платежа -->
    <remote_ip>127.0.0.1</remote_ip>                          <!-- IP-адрес, с которого создан платёж-->
    <manager_url>https://localhost:1500/billmgr</manager_url> <!-- URL по которому был открыт BILLmanager при создании платежа -->
    <phone>7 000 0000000</phone>                              <!-- Дополнительный параметр платежа, задаваемый в XML-файлах модуля -->
    <useremail>email@example.com</useremail>                  <!-- email-адрес пользователя, совершающего платёж-->
    <paymethod>                                               <!-- Информация о методе оплаты -->
      <id>1</id>                                              <!-- Код метода оплаты -->
      <name>XXX</name>                                        <!-- Наименование метода оплаты -->
      <active>on</active>                                     <!-- Статус -->
      <minamount>0.00</minamount>                             <!-- Минимальная сумма платежа -->
      <maxamount/>                                            <!-- Максимальная сумма платежа -->
      <autoclearperiod/>                                      <!-- Период автоудаления неоплаченных платежей -->
      <currency>126</currency>                                <!-- Код валюты метода оплаты -->
      <profiletype>1,2,3</profiletype>                        <!-- Типы плательщиков, которые могут использовать метод оплаты -->
      <commissionamount>0.00</commissionamount>               <!-- Сумма комиссии при оплате -->
      <commissionpercent>0</commissionpercent>                <!-- Процент комиссии при оплате -->
      <module>pmXXX</module>                                  <!-- Имя модуля -->
    </paymethod>
    <currency>                                                <!-- Информация о валюте, в которой совершается платёж-->
      <id>126</id>                                            <!-- Код валюты из справочника -->
      <name>Russian Ruble</name>                              <!-- Наименование -->
      <iso>RUB</iso>                                          <!-- Буквенный код валюты по ISO-->
      <code>643</code>                                        <!-- Цифровой код валюты по ISO -->
      <active>on</active>                                     <!-- Статус -->
    </currency>
    <project>                                                 <!-- Информация о провайдере -->
      <id>1</id>                                              <!-- Код -->
      <name>ISPsystem</name>                                  <!-- Наименование -->
      <notifyemail>email@example.com</notifyemail>            <!-- email для уведомлений -->
    </project>
    <items>                                                   <!-- Список позиций счёта, при привязке платежа к заказу содержит заказанные услуги, в противном случае описание назначения платежа -->
      <item>                                                  <!-- Позиция счёта -->
        <name>Advanced payment</name>                         <!-- Наименование -->
        <locale_name>Advanced payment</locale_name>           <!-- Наименование в локализации пользователя -->
        <amount>1.00</amount>                                 <!-- Сумма по позиции -->
      </item>
    </items>
  </payment>
</doc>

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

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

Скрипт обработки оповещений об изменении статуса платежа от платёжной системы принимает HTTP-запрос от платёжной системы (webhook), проверяет подпись, сверяет данные и вызывает одну из функций изменения статуса платежа:

Алгоритм работы скрипта результата:

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

Другие CGI-скрипты

Скрипт рекуррентных платежей (recurring_script)  показывает пользователю страницу привязки карты. После успешной привязки сохраняет токен и передаёт его в BILLmanager.

Функции BILLmanager

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

После совершения оплаты для возврата клиента в BILLmanager используются стандартные функции:

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

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

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

Пример иллюстрирует реализацию модуля платёжной системы по 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__, для формирования имени файла лога. 

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) — выполняет в BILLmanager функцию $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.

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

Кроме приведённого примера вы можете изучить примеры из пакета разработчика BILLmanager. BILLmanager содержит библиотеки, необходимые для работы модулей на С++. Для разработки собственных модулей обработчиков:

1. Подключитесь к серверу с платформой по SSH. Подробнее о подключении по SSH см. в статье Настройка рабочего места.
2. Установите пакет ПО:

apt-get install billmanager-corporate-dev

dnf install billmanager-corporate-devel

После установки содержимое пакета будет доступно в следующих директориях:

С++

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

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

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

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

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

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

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