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

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

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

В общих чертах жизненный цикл модуля оплаты в BILLmanager выглядит примерно следующим образом:

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

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

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

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

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

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

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

  • etc/xml/billmgr_mod_pm*XXX*.xml — XML описание модуля. Формат наименования файла строго регламентирован
  • paymethods/pm*XXX* — основной скрипт модуля. Формат наименования файла строго регламентирован
  • cgi/*XXX*payment — скрипт оплаты, не обязательный файл, наименование не регламентировано
  • cgi/*XXX*result — скрипт обработки оповещений, не обязательный файл, наименование не регламентировано
  • cgi/*XXX*recurring — скрипт активации рекуррентной оплаты, не обязательный файл, наименование не регламентировано
  • cgi/*XXX*recurringresult — скрипт обработки оповещений о рекуррентной оплате, не обязательный файл, наименование не регламентировано

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

Описание XML

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

Примерный вид XML файла модуля:

<?xml version="1.0" encoding="UTF-8"?>
<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">Свойствоop 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|/index.php/%D0%9E%D0%BF%D0%B8%D1%81%D0%B0%D0%BD%D0%B8%D0%B5_%D1%84%D0%BE%D1%80%D0%BC] формы, с учетом необходимости расположения полей в секции <page name="methodprops"></page> для корректного размещения полей на формах в BILLmanager. Единственным отличием от стандартного описание является поддержка атрибута private который запрещает вывод данного атрибута в XML при печати счета по созданному платежу. Используется для секретных данных, таких как пароль или секретный ключ. Страницы (page) с именами recurring и refundpage описывают настройки рекуррентных платежей и настройки отмены платежей, соответственно

Секция metadata с именем payment.edit.xxx отвечает за дополнительные поля, отображаемые клиенту при совершении оплаты. Так же описывается согласно стандартной схема описания [ XML|/index.php/%D0%9E%D0%BF%D0%B8%D1%81%D0%B0%D0%BD%D0%B8%D0%B5_%D1%84%D0%BE%D1%80%D0%BC] форм в BILLmanager.

Секция metadata с именем paymethod.transfer.XXX отвечает за дополнительные поля, отображаемые при переводе средств обратно клиенту. Так же описывается согласно стандартной схема описания [ XML|/index.php/%D0%9E%D0%BF%D0%B8%D1%81%D0%B0%D0%BD%D0%B8%D0%B5_%D1%84%D0%BE%D1%80%D0%BC] форм в BILLmanager.

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

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

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

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

Где

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

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

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

    <?xml version="1.0" encoding="UTF-8"?>
<doc>
  <feature>
    <refund>on</refund>
    <transfer>on</transfer>
    <recurring>on</recurring>
    <redirect>on</redirect>
    <noselect>on</noselect>
    <notneedprofile>on</notneedprofile>
    <pmtune>on</pmtune>
    <pmvalidate>on</pmvalidate>
    <crtune>on</crtune>
    <crvalidate>on</crvalidate>
    <crset>on</crset>
    <crdelete>on</crdelete>
    <rftune>on</rftune>
    <rfvalidate>on</rfvalidate>
    <rfset>on</rfset>
    <rctune>on</rctune>
    <rcvalidate>on</rcvalidate>
    <rcset>on</rcset>
    <rcpay>on</rcpay>
    <tftune>on</tftune>
    <tfvalidate>on</tfvalidate>
    <tfset>on</tfset>
  </feature>
  <param>
    <payment_script>/mancgi/qiwipullpayment.php</payment_script>
    <recurring_script>/mancgi/qiwipullrecurringpayment.php</recurring_script>
    <recurring_type></recurring_script>
  </param>
  <needprofileinfo>
    <country_legal/>
    <state_legal/>
    <postcode_legal/>
    <city_legal/>
    <address_legal/>
    <.../>
  </needprofileinfo>
</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 — в общем случае обязательная возможность для перевода средств. При вызове данной команды выполняются все необходимые действия для выполнения перевода

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

    • payment_script — пусть к скрипту переадресации на оплату относительно домена установки BILLmanager
    • recurring_script — пусть к скрипту переадресации на подтверждение активации рекуррентных платежей
    • recurring_type — битовая маска поддерживаемых возможностей рекуррентных платежей. Складывается из
      • 1 — платеж создается отдельно по каждой услуге
      • 2 — платеж создает по нескольким услугам
      • 7 — платеж создается по всем услугам
      • 8 — для регистрации платежа требуется указание максимально суммы
      • 20 — для подтверждения рекуррентного платежа требуется переадресация в платежную систему
      • 21 — для подтверждения необходимо выполнение клиентом дополнительных действий

Ветка needprofileinfo (не обязательно) содержит список параметров плательщика, необходимый для оплаты данным методом оплаты. Параметры указываются в виде списка внутренних имен параметров, которые можно узнать в справочнике стран — параметры.

  • 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 формы перевода, на выход ожидается измененная и дополненная XM
  • tfvalidate — вызывается для проверки введенных при переводе значений. На стандартный вход подается XML содержащая введенные на форме значения, на выход ожидается XML содержащая описание ошибок ввода, либо пустой XML документ
  • tfset — вызывается при нажатии ОК на форме перевода. На стандартный ввод подается XML содержащая данные о созданном для перевода платеже, сумму перевода, а так же параметры метода оплаты
  • rcdelete — вызывается при отключении автоплатежа. Параметром передается код профиля автоплатежа, который требуется удалить

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

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

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

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

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

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

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

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

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

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

<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'|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 при необходимости) выглядит примерно следующим образом:

<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|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}<code>643{code}</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.

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

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

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

  • Выделить из полученных от платежной системы данных код платежа в BILLmanager
  • По коду платежа получить информацию из базы данных либо при помощи функции payment.info информацию о платеже и параметрам метода оплаты
  • Сравнить данные полученные от платежной системы с данными хранящимися в BILLmanager
  • При наличии проверить контрольную подпись полученных данных с помощью секретного ключа (самый распространенный способ верификации полученных данных)
  • Изменить статус платежа в BILLmanager в соответствии с полученными данными с помощью одной из функций описанных ниже
  • При необходимости оповестить платежную систему об успешной или не успешной обработке входящего запроса

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

Функции BILLmanager

  • 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 страницы, либо стандартные функции BILLmanager:

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

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

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

PHP

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

  • etc/xml/billmgr_mod_pmqiwipull.php.xml — XML описание
  • paymethods/pmqiwipull.php — основной скрипт
  • cgi/qiwipullpayment.php — CGI скрипт перенаправления на оплату
  • cgi/qiwipullresult.php — получения уведомлений от платежной системы

А так же вспомогательного файла с полезными функциями:

  • include/php/bill_util.php

Скачать пример одним файлом можно по ссылке https://github.com/ISPsystemLLC/billmanager/blob/master/tar/qiwipull.tar.gz , так же все файлы можно просмотреть онлайн — https://github.com/ISPsystemLLC/billmanager/

Функции 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

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

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

 yum install billmanager-standard-devel

После этого примеры можно найти в директории:

/usr/local/mgr5/src/examples

С++

Описание

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

Так же при написании модулей могут быть полезные следующие материалы

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

Модуль состоит из двух обязательных файлов pminterkassa.cpp — код основного исполняемого файла модуля оплаты и xml/billmgr_mod_pminterkassa.xml — XML описания модуля.

Так же в модуль входят два CGI скрипта — переадресации на оплаты в процессинговый центр и скрипт приема оповещений о зачислении платежей.