Bitrix Framework

System features allow customizing and adding you own custom payment systems, represented in core D7 as classes. Accordingly, you can use mechanism of inheriting:

• when you need to create payment system similar to the one included into the product distribution package, you can implement inheriting from the corresponding class;
• when you need to write a payment system from zero, you can inherit from base class Bitrix\Sale\PaySystem\BaseServiceHandler or \Bitrix\Sale\PaySystem\ServiceHandler
  
  Most frequently, the class \Bitrix\Sale\PaySystem\ServiceHandler (descendant of class Bitrix\Sale\PaySystem\BaseServiceHandler) is used for customization. The class \Bitrix\Sale\PaySystem\ServiceHandler supports methods that will enable processing response from payment system.

You can add your own payment system handler to the namespace \Sale\Handlers\PaySystem\, otherwise it won't be connected.

Example of inheriting payment systems:

class YahooHandler extends ServiceHandler implements IReturn, IHold
{
    public static function initiatePay(Payment $payment)
    {
        $params = array('URL' = > $this->getUrl($payment, 'pay'));
        $this->setExtraParams($params);
        
        return $this->showTemplate($payment, "template");
    }

    public static function getIndicativeFields()
    {
        return array('BX_HANDLER' => 'Yahoo');
    }
}

System will search for handler in the following directories:

protected static $handlerDirectories = array(
	'CUSTOM' =>  path is sourced from the option path2user_ps_files (by default "/php_interface/include/sale_payment/")
	'LOCAL' => '/local/php_interface/include/sale_payment/',
	'SYSTEM' => '/bitrix/modules/sale/handlers/paysystem/'
	'SYSTEM_OLD' => '/bitrix/modules/sale/payment/'
)

Important!

If you don't change the name when copying (keep /bitrix/php_interface/include/sale_payment/yahoo), you can use only a custom handler in the payment system settings. System handler (that was copied) won't be available: now custom handler replaces the system handler.

This leads to the following: when copying a system handler to its namespace, it's name changes and the class must be renamed. For example, if we have copied a system 'yahoo' to /bitrix/php_interface/include/sale_payment/yahoonew, the inheriting in the file handler.php must looks as follows:

class YahooNewHandler extends PaySystem\BaseServiceHandler

Restrictions on payment system use

You may limit the use of payment system by specific parameters. For example, by delivery system. To do it, apply standard restrictions. When you need something specific, create your own types of restrictions.

Requirements to the .description.php file for payment system handler

Array structure with payment system handler settings is stored in the variable $data and looks as follows:

$data = array(
	'NAME' => 'payment_system_name',
	'SORT' => 500,
	'CODES' => array( // array with parameters, necessary for configuration
		"КОД_ПАРАМЕТРА" => array(
			"NAME" => 'PARAMETER_NAME',
			"DESCRIPTION" => 'PARAMETER_DESCRIPTION',
			'SORT' =>100,
			'GROUP' => 'GROUP_CODE',
			'DEFAULT' => array( // default value
				'PROVIDER_KEY' => 'KEY', // value type: (PAYMENT, ORDER, SHIPMENT, USER, COMPANY, VALUE)
				'PROVIDER_VALUE' => 'DATE_BILL' // value: field from specific entity or an arbitrary value
			)
		),
		...
	)
);

When showing the description when creating a handler, you have to declare the variable $description:

$description = array(
	'MAIN' => 'HANDLER DESCRIPTION'
);