Last Modified: 10.10.2012
A payment system is the means by which a customer can pay for their order: on-line payments, wire transfers etc. The system allow to create and use as many payment systems as you want. For example, the system comes preconfigured to use the following payment systems (e-Store -> e-Store Settings -> Payment systems):
Let us add a new payment system. Click New payment system and select the site to which the system will be added:
In other words, payment system is a subject of a current site. Depending on the site, customers will enjoy different payment systems.
The following figure illustrates the possible payment system parameters:
The first tab contains general parameters of the payment system. Other tabs reflect payer types defined for a given site. Each tab specify the payment system parameters for each payer type, individually. For example, the following picture shows parameters for the payer type Private 1:
These tabs has the following options.
- Applied to this payer type: if marked, the payment system can be used with a given payer type.
- Name: specifies the name of the payment system as it will be displayed to a customer.
- Handler: select here the script that the system will call to handle the payment system.
- Open in a new window: specifies that any result obtained from the script (e.g. printable invoice) will be displayed in a new window.
- Handler properties. This section is available if only the selected payment system handler provides custom properties that you can configure. You can show or hide the property section by clicking the link Show handler properties or Hide handler properties.
Payment system handlers
Different payment systems has different interaction protocols and interfaces. Sometimes, the interfaces can differ dramatically. For example, Payflow Pro requires a special SDK to be installed on a server; while generic banking payment system needs printing a hard-copy receipt. Therefore, payment system integration is performed via special PHP scripts - payment system handlers.
The handlers are created for each payment system and called immediately upon checking-out, or when a customer has chosen to repeat payment in their personal section. The handlers can display a printable receipt, or send data to a remote payment processor etc.
A common scenario of usage of the handlers are as follows.
- Copy all required handler files from /bitrix/modules/sale/payment/ to /bitrix/php_interface/include/sale_payment/.
Note that the custom handler storage folder /bitrix/php_interface/include/sale_payment/
is not mandatory. You can use any other directory, but you will have to specify it in the module settings:
- Edit files in /bitrix/php_interface/include/sale_payment/ so that they meet your requirements. Typical modifications could be: changing test usernames and passwords; adding a receipt stamp image; altering the receipt design etc.
- Add your custom handlers for other payment systems if needed.
- An offline payment system handler can display a receipt ready to be printed out.
This handler is a script that displays a document whose order parameters are properly inserted and formatted.
You can find an example of such handler in /bitrix/modules/sale/payment/bill/payment.php.
- A typical online payment system handler displays a form that sends data obtained from a customer to a payment collector. Examples of such systems are Assist, Authorize.Net, Payflow, WorldPay.
The design and fields of the HTML form completely depend on the payment system. Usually, you will find the detailed description of required fields in the payment system documentation.
You will find an example of an online handler in /bitrix/modules/sale/payment/paypal/payment.php.
As a rule, online payment collectors offer one of the following integration interface models (sometimes both):
- order parameters are sent to the collector site where a customer fills additional forms (e.g. provides credit card details) and performs the payment;
- a customer provides all the required parameters by filling in the payment form on the site; the handler builds a request to the payment collector; finally, the collector returns with the payment result.
The first option is the simplest in the view of integration. It is sufficient to create an HTML form that will send data to the payment collector, having provided the required fields. A good example of this approach can be found in /bitrix/modules/sale/payment/assist/payment.php.
The second variant can seem more sophisticated, but it is far more flexible. You can take a look at the implementation in /bitrix/modules/sale/payment/authorizenet/.