Интеграция с платежными системами (до версии 16.0.2)

Описание

Под платежными системами в этой статье понимаются любые способы оплаты заказа: как платежные системы, принимающие платежи on-line, так и банковские переводы, и т.п.

Разные платежные системы предлагают различные интерфейсы для интеграции (взаимодействия). Зачастую эти интерфейсы отличаются кардинально: например, интеграция с системой PayFlow Pro требует выполнения запросов к платежной системе при помощи устанавливаемого на сервер SDK, а интеграция со сбербанком требует распечатки квитанции сбербанка. Поэтому интеграция с платежными системами осуществляется посредством php-скриптов, называемых обработчиками платежных систем.

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

• payment.php - если обработчик вызывается в после фактического сохранения всех параметров заказа в базу данных. Применяется в стандартном компоненте процедуры заказа;
• pre_payment.php - если требуется вызвать обработчик в внутри процедуры заказа (для тех обработчиков, которые могут сразу произвести оплату заказа и вернуть результат). Применяется в двушаговом компоненте процедуры заказа;
• action.php - применяется для снятия с карты заданной суммы денег (только для обработчиков, которые могут сразу произвести оплату заказа и вернуть результат). Например, при продлении подписки.

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

Типичные обработчики

Типичным обработчиком для платежной системы, которая не осуществляет on-line платежи, является вывод на экран счета (или квитанции), готового к печати на принтере. Примерами таких обработчиков являются счет или квитанция перевода через сбербанк.

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

Пример такого обработчика можно посмотреть в шаблонах платежных систем сбербанка (/bitrix/modules/sale/payment/sberbank.php), банковского перевода (/bitrix/modules/sale/payment/bill.php).

Типичным обработчиком для платежной системы, которая осуществляет платежи on-line, является вывод на экран HTML-формы, которая отправляет данные платежной системе. Примерами таких платежных систем являются Assist, AuthorizeNet, Payflow, WorldPay.

Вид, набор полей и прочие параметры HTML-формы полностью зависят от платежной системы. Конкретное описание формы, которая требуется данной платежной системе, следует искать в документации по этой платежной системе.

Пример такого обработчика можно посмотреть в шаблонах платежных систем Assist (/bitrix/modules/sale/payment/assist.php), AuthorizeNet (/bitrix/modules/sale/payment/authorizenet.php), Paypal (/bitrix/modules/sale/payment/paypal.php) и т.д.

Параметры, которые необходимы платежным системам, можно получать из параметров заказа, которые доступны в обработчике в массиве $arOrder, а так же из значений свойств заказа, которые можно получить следующим образом:

// В результате выполнения следующего кода мы получим ассоциативный массив,
// в котором символьным кодам свойств заказа (или ID свойств, если символьные коды не установлены)
// будут поставлены значения свойств, которые были введены при оформлении этого заказа
// $ORDER_ID - код заказа - предустановленная переменная для обработчика
$arCurOrderProps = array();
$db_res = CSaleOrderPropsValue::GetList(($b=""), ($o=""), array("ORDER_ID"=>$ORDER_ID));
while ($ar_res = $db_res->Fetch())
	$arCurOrderProps[(strlen($ar_res["CODE"])>0) ? $ar_res["CODE"] : $ar_res["ID"]] = $ar_res["VALUE"];
// Теперь можно сформировать форму, которая нужна данной платежной системе,
// определив соответствие между свойствами заказа в базе и параметрами, 
// необходимыми платежной системе
if (isset($arCurOrderProps["ADDRESS"])):
	?><input type="hidden" name="address" value="<?= htmlspecialchars($arCurOrderProps["ADDRESS"]) ?>"><?
endif;
if (isset($arCurOrderProps["ZIP"])):
	?><input type="hidden" name="postcode" value="<?= htmlspecialchars($arCurOrderProps["ZIP"]) ?>"><?
endif;
// Мы записали значение, которое покупатель ввел для свойства с кодом ADDRESS, в то поле, в котором 
// платежная система принимает адрес покупателя. Мы записали значение, которое покупатель ввел для 
// свойства с кодом ZIP, в то поле, в котором платежная система принимает почтовый индекс.

Как правило платежные системы с on-line платежами предоставляют один из двух (иногда оба) типов интерфейса для интеграции: 1. форма с параметрами заказа отправляется на сайт платежной системы, где покупатель заполняет дополнительные формы (например, вводит номер пластиковой карты) и производит фактическую оплату, 2. все параметры заполняются на сайте и формируется запрос к платежной системе, в ответе на который она сообщает результат оплаты.

Первый тип интерфейса является наиболее простым для интеграции. В обработчике достаточно создать HTML-форму, которая будет отправлять данные на сайт платежной системы, и добавить в форму необходимые платежной системе поля. Конкретные параметры необходимо смотреть в системе помощи по конкретной платежной системе. Пример такого обработчика можно посмотреть в шаблоне платежной системы Assist (/bitrix/modules/sale/payment/assist.php).

Второй тип является более сложным для интеграции, но зато он является более гибким в плане возможностей. Пример такого обработчика можно посмотреть в шаблоне платежной системы AuthorizeNet (/bitrix/modules/sale/payment/authorizenet.php). Общая структура кода обработчика в этом случае может быть примерно такой:

// Если готовы запросить платежную систему
if ($_REQUEST["pay_this_order"]=="Y")
{
	// Соберем в $strPostQueryString строку параметров запроса
	$strPostQueryString = "x_login=".urlencode("login");
	$arCurOrderProps = array();
	$db_res = CSaleOrderPropsValue::GetList(($b=""), ($o=""), array("ORDER_ID"=>$ORDER_ID));
	while ($ar_res = $db_res->Fetch())
		$arCurOrderProps[(strlen($ar_res["CODE"])>0) ? $ar_res["CODE"] : $ar_res["ID"]] = $ar_res["VALUE"];
	if (isset($arCurOrderProps["ADDRESS"]))
		$strPostQueryString .= "&x_address=".urlencode($arCurOrderProps["ADDRESS"]);
	* * *
	if (isset($arCurOrderProps["ZIP"]))
		$strPostQueryString .= "&x_ship_to_zip=".urlencode($arCurOrderProps["ZIP"]);
	// Запросим платежную систему
	$strResult = QueryGetData("some_url.net", 443, "/some_path/file.dll", $strPostQueryString, $errno, $errstr, "POST", "ssl://");
	// В $strResult вернулся ответ платежной системы. Его вид зависит от платежной системы.
	// Можно обработать его и сохранить в соответствующих полях заказа.
	* * *
}
else
{
	?>
	<form action="" method="post">
		Credit card number: <input type="text" name="ccard_num" size="30"><br>
		* * * <br>
		CVV2: <input type="text" name="ccard_code" size="5"><br>
		<input type="hidden" name="CurrentStep" value="<?= $CurrentStep ?>">
		<input type="hidden" name="ORDER_ID" value="<?= $ORDER_ID ?>">
		<input type="hidden" name="pay_this_order" value="Y">
		<input type="submit" value="Proceed">
	</form>
	<?
}

В последнем случае (интерфейс типа 2) модуль Интернет-магазина сразу получает результат работы платежной системы, пригодный для дальнейшей обработки заказа.

В случае интерфейса типа 1 может оказаться удобным автоматически забирать результаты работы платежной системы (оплачен ли реально заказ). Конечно это возможно только в том случае, если платежная система предоставляет соответствующий интерфейс. Узнать подробности об этом интерфейсе следует в документации по соответствующей платежной системе или в службе техподдержки этой системы. Если платежная система предоставляет интерфейс для получения статуса оплаты заказа, то можно реализовать скрипт автоматического получения этих статусов. Указанный скрипт вызывается из формы управления заказами (административной части сайта) (Смотри Пользовательскую документацию, раздел "Заказы")для каждого из заказов, оплаченных с помощью данной платежной системы. Создать новый скрипт автоматического запроса статуса оплаты можно следующим образом:

1. Необходимо создать в публичной части сайта (например, в папке /bitrix/php_interface/include/payment/) файл запроса статуса. За основу можно взять один из предустановленных скриптов из папки /bitrix/modules/sale/payment/ (например, assist_res.php).
2. Необходимо изменить скрипт таким образом, чтобы он соответствовал интерфейсу платежной системы.
3. Необходимо в форме редактирования параметров соответствующей платежной системы (в административной части сайта) (См. Пользовательскую документацию, раздел "Создание и редактирование платежной системы") указать, для каких обработчиков платежных систем действует этот скрипт автоматического получения статуса заказа.

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

В случае реализации собственного компонента оформления заказа структура и алгоритм работы обработчика платежной системы могут быть совершенно произвольными. Однако, есть одна особенность. В отличие от "обычных" языковых файлов в скриптах системы, языковой файл для .description.php подключается с помощью include(). А так как .description.php подключается с использованием LocalGetPSActionParams(), то необходимо объявление global $MESS;