BILLmanager 6
Documentation
/
BILLmanager 6
/
Developer section
/
Creating modules
/
How to add a payment gateway module
en En
es Es
Add to Favorites
Focus mode
Documentation
/
BILLmanager 6
/
Developer section
/
Creating modules
/
How to add a payment gateway module

How to add a payment gateway module

The payment system module is responsible for:

  • the set of connection settings;
  • the appearance of the settings form;
  • the appearance and behavior of the payment form on the client side.

The payment module also implements mechanisms for issuing, processing, and crediting a client's payment. Depending on the requirements, the module may implement various behavioral logic when making a payment — redirecting the client to the payment system website to complete the payment or issuing an invoice and waiting for the client to make the payment.

How the module works

The lifecycle of the payment module in BILLmanager:

  1. Module installation.
  2. Adding a connection to the payment system.
  3. Client creates a payment.
  4. Client pays the issued invoice.
  5. Crediting or canceling the payment.

Install the module:

  • manually, if it is provided as a set of files;
  • from the standard repository using a package manager.

After installation, the module becomes available for selection when creating a payment method in BILLmanager.

The platform polls each module at startup to learn about supported capabilities and required parameters. This speeds up operation: unsupported calls are excluded and the behavior of forms is determined when the client makes a payment.

Module structure

A payment system module consists of two or more files. The main files are the XML description of the module and a script that passes the module configuration to the platform. Typically, two CGI scripts are used: one for redirecting the client to the payment system website and another for receiving notifications about payment status changes from the payment system.

If the payment system has additional integration requirements or at the developer's discretion, other files can be added. For example, files responsible for rendering additional forms, additional validation of payment parameters, printing receipts, checking payment statuses on a schedule, etc.

The standard list of module files is as follows (paths are relative to the BILLmanager installation directory):

  • etc/xml/billmgr_mod_pmXXX.xml — XML description of the module. The file naming format is strictly regulated;
  • paymethods/pmXXX — the main module script. The file naming format is strictly regulated;
  • cgi/XXXpayment — the payment script, optional file, naming is not regulated;
  • cgi/XXXresult — the notification handling script, optional file, naming is not regulated;
  • cgi/XXXrecurring — the recurring payment activation script, optional file, naming is not regulated;
  • cgi/XXXrecurringresult — the recurring payment notification handling script, optional file, naming is not regulated.

Where XXX is the module name specified in Latin characters. If the main module script name contains a file extension, it is also included in the module name. For example, if your script is named pmpay.php, then the module name is pay.php, not pay.

XML description

The file name must follow the format billmgr_mod_pmXXX.xml, where XXX is the module name. The file is copied to the /etc/xml directory relative to the BILLmanager installation path. The file contains a description of the module itself (described as a plugin), as well as descriptions of additional forms and messages.

Example XML file

Here, the <plugin> element is responsible for describing the module itself. The name attribute matches the name of the payment module. Inside the element, there can be one group element with the value payment_method, which indicates that this module is used for payment methods, and several msg elements. The lang attribute of the element indicates which language the message belongs to, and the name attribute can have the following values:

  • desc_short — short description of the module. Displayed when selecting a payment module in BILLmanager;
  • desc_full — full description of the module. Displayed when building the list of installed modules in COREmanager.

The metadata element named paymethod.edit.XXX is responsible for the additional fields of the module when adding and configuring a payment method. It is formed according to the standard XML form description. Place the fields inside the <page name="methodprops"></page> element for correct placement of fields on forms in BILLmanager. The only difference from the standard description is the support for the private attribute, which prevents this attribute from being output in the XML when printing an invoice for a created payment. It is used for sensitive data such as a password or secret key. The page elements named recurring and refundpage describe the recurring payment settings and payment cancellation settings, respectively.

The metadata element named payment.edit.XXX is responsible for the additional fields that the client sees when making a payment. It is also described according to the standard XML form schema in BILLmanager.

The metadata element named paymethod.transfer.XXX is responsible for the additional fields displayed when transferring funds back to the client. It is also described according to the standard XML form description schema in BILLmanager.

The lang element contains translations of field names on the form according to the standard translation description schema. The <messages name="label_paymethod"> section is responsible for the label of the module name in the payment methods list.

Main module script

The main payment module script is responsible for passing information about the functions supported by the module to BILLmanager, as well as handling some of these functions. When working with the module, BILLmanager executes the script file with the following parameters:

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

Where:

  • cmd — control command;
  • id — payment code;
  • amnt — amount in the currency of the payment method (used for refunds and fund transfers).

The following values can be passed to the --command parameter:

  • config — request for the module configuration. In response, the module must return an XML document to the standard output:
    Example XML document

The feature element contains a list of payment module capabilities. If a capability is not supported, it must not be present in the command execution output.

List of allowed values:

  • refund — indicates support for payment cancellation and refunds. Without this capability, handling of the rftune, rfvalidate, rfset commands is not required;
  • transfer — indicates support for transferring funds from the payment system account to the client's account. Without this capability, handling of the tftune, tfvalidate, tfset commands is not required;
  • recurring — indicates support for recurring payments. Without this capability, the recurring_script and recurring_type parameters can be omitted;
  • redirect — indicates that to make a payment, the module redirects the client to the payment system;
  • noselect — the payment method will not be displayed in the list when the client selects one. Used when no preliminary creation of a payment in BILLmanager is required for the payment. For example, when paying via a terminal;
  • notneedprofile — specified if indicating a payer is not required to make a payment. However, if the payment method is connected to a company, the system will ask the client to create or select a payer;
  • pmtune — specified if additional actions need to be performed for the correct display of the payment method settings form. See the description of the pmtune command for details;
  • pmvalidate — if specified, the module will be called to validate the entered values when saving payment method parameters;
  • crtune — specified if additional actions need to be performed for the correct display of the payment form. See the description of the crtune command for details;
  • crvalidate — if specified, the module will be called to validate the entered values when saving the values entered by the client;
  • crset — specified if:
    • any actions by the module are required before redirecting to payment;
    • the payment is made without navigating to the payment system;
    • client data entry is required during payment;
  • crdelete — specified if actions on the payment system side are required for proper deletion of a payment;
  • rftune — similar to crtune, but for refunds;
  • rfvalidate — similar to crvalidate, but for refunds;
  • rfset — a mandatory capability for refunds. When the command is called, the module performs all necessary actions for the refund;
  • rctune — similar to crtune, but for recurring payments;
  • rcvalidate — similar to crvalidate, but for recurring payments;
  • rcset — similar to crset, but for setting up recurring payments on the client side. Used for configuring recurring payments on the payment system side;
  • rcpay — called when a recurring payment is created in BILLmanager. Used to initiate payment on the payment system side;
  • rcdelete — specified if actions on the payment system side are required for proper deletion of an auto-payment profile;
  • tftune — similar to crtune, but for fund transfers;
  • tfvalidate — similar to crvalidate, but for fund transfers;
  • tfset — a mandatory capability for fund transfers. When the command is called, the module performs all necessary actions for the transfer.

The param element contains a list of payment method parameters. The following are supported:

  • payment_script — path to the payment redirection script relative to the BILLmanager installation domain. For example, if the script is located at http://domain.com/cgi/pullpayment.php , specify /mancgi/pullpayment.php
  • recurring_script — path to the script for redirecting to confirm the activation of recurring payments. For example, if the script is located at http://domain.com/cgi/pullrecurringpayment.php , specify /mancgi/pullrecurringpayment.php
  • recurring_type — bit mask of supported recurring payment options. It is formed by setting the corresponding bits to one using a bitwise left shift and bitwise OR. The numbers listed are bit positions, not decimal values ​​for arithmetic addition. Available bit positions:
    • 1 — a payment is created separately for each service;
    • 2 — a payment is created for multiple services;
    • 7 — a payment is created for all services;
    • 8 — specifying a maximum amount is required to register a payment;
    • 20 — redirection to the payment system is required to confirm a recurring payment;
    • 21 — additional actions by the client are required for confirmation.
    Пример
  • pmtune — called to modify the payment method settings form. An XML settings form is passed to the script's standard input, and a modified and extended XML form is expected as output;
  • pmvalidate — called to validate the values entered in the payment method settings. An XML document containing the values entered on the form is passed to the standard input, and an XML document containing a description of input errors, or an empty XML document, is expected as output;
  • crtune — called to modify the payment form. An XML payment form is passed to the script's standard input, and a modified and extended XML is expected as output;
  • crvalidate — called to validate the values entered during payment. An XML document containing the values entered on the form is passed to the standard input, and an XML document containing a description of input errors, or an empty XML document, is expected as output;
  • crset — called when OK is clicked on the payment form. The payment code is passed as a parameter, which can be used to retrieve all necessary data. The platform saves the data entered by the user to the database;
  • crdelete — called when Delete is clicked in the payment list. The code of the payment to be deleted is passed as a parameter;
  • rftune — called to modify the refund form. An XML refund form is passed to the script's standard input, and a modified and extended XML form is expected as output;
  • rfvalidate — called to validate the values entered during a refund. An XML document containing the values entered on the form is passed to the standard input, and an XML document containing a description of input errors, or an empty XML document, is expected as output;
  • rfset — called when OK is clicked on the refund form. An XML document containing the following is passed to the standard input:
    • data about the original or newly created refund payment;
    • data about the refund amount;
    • a description of the reason for the refund;
    • payment method parameters;
  • tftune — called to modify the fund transfer form. An XML transfer form is passed to the script's standard input, and a modified and extended XML form is expected as output;
  • tfvalidate — called to validate the values entered during a transfer. An XML document containing the values entered on the form is passed to the standard input, and an XML document containing a description of input errors, or an empty XML document, is expected as output;
  • tfset — called when OK is clicked on the transfer form. An XML document containing data about the payment created for the transfer, the transfer amount, and payment method parameters is passed to the standard input;
  • rcdelete — called when an auto-payment is disabled. The code of the auto-payment profile to be deleted is passed as a parameter.

An example of the script implementation can be found at the end of the article.

Module CGI scripts

CGI scripts are an optional part of the payment module. They may be absent if all the logic is implemented in the main module. For example, when paying via a WebMoney wallet, the invoice is issued to the user directly by the main module script and its payment is checked on a schedule.

There may also be cases where the module contains several CGI scripts:

  • for payment;
  • for receiving notifications about payment status changes;
  • other scripts required by the payment system.

For example, for integration with YooMoney, an additional CGI script is implemented that validates the data entered by the client on the YooMoney side. To do this, the payment system calls the script and passes it the data entered by the client, as well as a parameter responsible for the operation type — check.

CGI scripts can be located on a server different from the BILLmanager server, or on a different IP address or domain. Everything depends on the requirements of the module developer and the payment system. For example, there are schemes where authorization when sending a payment status change notification is performed using a client certificate. In this case, the script needs to be placed on a separate VirtualHost configured to handle client certificates. But most often there is no specific integration requirement, and to simplify maintenance of the payment module, it is recommended to place CGI scripts in the standard BILLmanager directory — /usr/local/mgr5/cgi

As an example, let us examine scripts of the following types:

  • redirection to payment;
  • receiving status change notifications.

Payment redirection script

BILLmanager receives the address of the payment redirection script along with the module data upon first access to it. Most often, the script generates a form with the necessary parameters and automatically submits it.

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

The elid parameter containing the payment code is always passed to the payment redirection script. Using the value of this parameter, the payment.info function can retrieve all the data needed to generate the payment form. The function returns a response in XML or JSON format:

More details

All parameters that need to be additionally specified by clients during payment are added to the payment element. All payment method parameters are added to the paymethod element. This method of retrieving payment information is preferable to directly querying the BILLmanager database.

An example of the redirection script can be found at the end of the article.

Payment status change notification script

The script for handling payment status change notifications from the payment system performs the following actions:

  1. Extracts the payment code in BILLmanager from the data received from the payment system;
  2. Retrieves information about the payment and payment method parameters using the payment code:
  3. Compares the data received from the payment system with the data stored in BILLmanager;
  4. If the received data contains a control signature, verifies it using the secret key;
  5. Changes the payment status in BILLmanager according to the received data using one of the functions described below;
  6. If necessary, notifies the payment system about successful or unsuccessful processing of the incoming request.

An example of the payment notification handler script can be found at the end of the article.

BILLmanager functions

FunctionDescriptionParameters
payment.infoDisplays all available information about the payment.
  • elid — payment code.

payment.setfraud

Marks the payment as fraudulent.
  • elid — payment code;
  • info — additional information;
  • externalid — payment code in the payment system.

payment.setinpay

Marks the payment as being paid.
  • elid — payment code;
  • info — additional information;
  • externalid — payment code in the payment system.

payment.setnopay

Marks the payment as unpaid.
  • elid — payment code;
  • info — additional information;
  • externalid — payment code in the payment system.

payment.setpaid

Credits the payment.
  • elid — payment code;
  • info — additional information;
  • externalid — payment code in the payment system.

payment.success

Displays the page for successful payment completion.
  • elid — payment code;
  • module — integration module name.

payment.fail

Displays the payment error page.
  • elid — payment code;
  • module — integration module name.

Return pages

To return the client to the billing platform after making a payment, you can use:

  • custom-developed CGI scripts;
  • static HTML pages;
  • standard BILLmanager functions.

In all cases:

  • payment.success — the page for successful payment completion, where elid is the payment code;
  • payment.fail — the payment error page, where elid is the payment code.

To extend the forms displayed by the functions, specify the following in the plugin XML description:

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

Module example

The example illustrates the implementation of a payment module using the PULL (REST) protocol.

PHP

The module consists of the following main files:

  • etc/xml/billmgr_mod_pmpull.php.xml — XML description;
  • paymethods/pmpull.php — main script;
  • cgi/pullpayment.php — CGI script for redirection to payment;
  • cgi/pullresult.php — CGI script for receiving notifications from the payment system.

And also an auxiliary file:

  • include/php/bill_util.php

Functions in bill_util.php

Before including the bill_util.php file in your script, you must define the __MODULE__ macro to form the log file name.

Example of defining the _MODULE_ macro
set_include_path(get_include_path() . PATH_SEPARATOR . "/usr/local/mgr5/include/php"); 
define('__MODULE__', "pmXXX"); 
require_once 'bill_util.php';

The bill_util.php file provides the following functions:

  • Debug($str) — outputs $str as additional information to the log;
  • Error($str) — outputs $str as an error message to the log;
  • LocalQuery($function, $param, $auth = NULL) — executes the $function function in BILLmanager, passing it parameters from the $param array and the session code from $auth;
  • HttpQuery($url, $param, $requesttype = "POST", $username = "", $password = "", $header = array("Accept: application/xml")) — sends a request to $url with parameters from $param using the request type $requesttype and authorization data from $username and $password. Additional headers can also be passed in $header;
  • CgiInput($skip_auth = false) — retrieves an array of parameters received by the script in the query string or POST data. The $skip_auth parameter controls whether the auth parameter is retrieved from cookies if it is absent from the received data;
  • ClientIp() — retrieves the IP address from which the script was called;
  • class Error — defines an error class that simulates the behavior on errors in COREmanager.

C++ (using BILLmanager libraries)

Using BILLmanager header files for developing custom handler modules is available starting from BILLmanager version 5.58.0. In addition to the provided example, you can study the examples included in the BILLmanager developer package — billmanager-[BILLmanager Edition]-devel:

dnf install billmanager-corporate-devel
or
dnf install billmanager-devel
Explanations

Examples can be found in the /usr/local/mgr5/src/examples directory

C++

An example module is located at https://github.com/ISPsystemLLC/interkassa. The module uses COREmanager and BILLmanager header files and is based on the examples of building custom components described in the articles How to build custom components and Lower-level interaction, C++ plug-ins.

Materials from the Developer section of the BILLmanager documentation may also be useful when writing modules.

Module structure

The module consists of the following required files:

  • pminterkassa.cpp — code of the main executable file of the payment module;
  • xml/billmgr_mod_pminterkassa.xml — XML description of the module.

The module also includes CGI scripts:

  • a script for redirecting to payment to the processing center;
  • a script for receiving notifications about payment crediting.