sale.paysystem.handler.add

Описание

sale.paysystem.handler.add(
	fields
)

Метод добавляет рест-обработчик.

Параметры

Примеры

Пример 1

BX24.callMethod(
	"sale.paysystem.handler.add",
	{
		'NAME' : 'Обработчик.Rest', 	// Название обработчика
		'SORT' : 100, 	// Сортировка
		'CODE' : 'resthandlercode', 	// Уникальный код обработчика в системе
		'SETTINGS' : { 		// Настройки обработчика
			'CURRENCY' : {'RUB'}, 	// Список валют, которые поддерживает обработчик
			'FORM_DATA' : { 	// Настройки формы
				'ACTION_URI' : 'https://payment_service_url', 	// URL, на который будет отправляться форма
				'METHOD' : 'POST', 	// Метод отправки формы
				'PARAMS' : { 
// Карта соответствия полей между полями формы и параметрами обработчика: массив вида array(код_поля => код_параметра_обработчика)
					'serviceid' : 'REST_SERVICE_ID',
					'invoiceNumber' : 'PAYMENT_ID',
					'Sum' : 'PAYMENT_SHOULD_PAY',
					'customer' : 'PAYMENT_BUYER_ID',
				}
			},
			'CODES' : {		// Список параметров обработчика
				"REST_SERVICE_ID" : {	// Код параметра
					"NAME" : 'Номер магазина',	// Название параметра
					"DESCRIPTION" : 'Номер магазина',	// Описание параметра
					'SORT' : 100,	// Сортировка
				},
				"REST_SERVICE_KEY" : {
					"NAME" : 'Секретный ключ',
					"DESCRIPTION" : 'Секретный ключ',
					'SORT' : 300,
				},
				"PAYMENT_ID" : {
					"NAME" : 'Номер оплаты',
					'SORT' : 400,
					'GROUP' : 'PAYMENT',
					'DEFAULT' : {
						'PROVIDER_KEY' : 'PAYMENT',
						'PROVIDER_VALUE' : 'ACCOUNT_NUMBER'
					}
				},
				"PAYMENT_SHOULD_PAY" : {
					"NAME" : 'Сумма оплаты',
					'SORT' : 600,
					'GROUP' : 'PAYMENT',
					'DEFAULT' : {
						'PROVIDER_KEY' : 'PAYMENT',
						'PROVIDER_VALUE' : 'SUM'
					}
				},
				"PS_CHANGE_STATUS_PAY" : {
					"NAME" : 'Автоматическая смена статуса оплаты',
					'SORT' : 700,
					"INPUT" : {
						'TYPE' : 'Y/N'
					},
				},
				"PAYMENT_BUYER_ID" : {
					"NAME" : 'Код покупателя',
					'SORT' : 1000,
					'GROUP' : 'PAYMENT',	// тип значения строка, чекбокс и т.д.
					'DEFAULT' : {	// Значение по умолчанию
						'PROVIDER_KEY' : 'ORDER',	// Тип значения(см. доступный список ниже)
						'PROVIDER_VALUE' : 'USER_ID'	// Значение(см. доступный список ниже)
					}
				}
			}
		}
	},
	function(result)
	{
		if(result.error())
			console.error(result.error());
		else
			console.info("Обработчик добавлен с ID " + result.data());
	}
);

Пример 2

Начиная с версии 20.5.0 модуля sale добавлено новое значение FIELDS вместо старого PARAMS (появилась возможность передавать произвольные поля для REST-обработчиков платёжных систем).

Если значение ключа CODE - строка, то значение будет использоваться для поиска соответствия между полями формы и параметрами обработчика: массив вида array('CODE' => 'код_параметра_обработчика'). Название и значение будут получены из параметров обработчика ('CODES').

Если в ключе CODE передан объект, то в форме оплаты будет добавлено поле указанного типа. Поддерживаются типы:

• STRING (строка)
• Y/N (чекбокс)
• ENUM (список)

По умолчанию поля формы скрыты. Чтобы сделать поле видимым, необходимо передать 'VISIBLE' : 'Y'.

BX24.callMethod(
	"sale.paysystem.handler.add",
	{
		'NAME' : 'Обработчик.Rest',
		'SORT' : 100,
		'CODE' : 'resthandlercodedoc',
		'SETTINGS' : {
			'CURRENCY' : ['RUB'],
			'FORM_DATA' : {
				'ACTION_URI' : 'https://payment_service_url',
				'METHOD' : 'POST',
				'FIELDS' : { 
					'phone' : {
						'CODE': {
							'NAME' : 'Номер телефона',
							'TYPE' : 'STRING',
						}
						'VISIBLE' : 'Y',
					},
					'paymentId' : {
						'CODE' : 'PAYMENT_ID',
						'VISIBLE' : 'Y'
					},
					'serviceid' : {
						'CODE' : 'REST_SERVICE_ID'  
					}
				}
			},
			'CODES' : {
				"REST_SERVICE_ID" : {
					"NAME" : 'Номер магазина',
					"DESCRIPTION" : 'Номер магазина',
					'SORT' : 100,
				},
				"REST_SERVICE_KEY" : {
					"NAME" : 'Секретный ключ',
					"DESCRIPTION" : 'Секретный ключ',
					'SORT' : 300,
				},
				"PAYMENT_ID" : {
					"NAME" : 'Номер оплаты',
					'SORT' : 400,
					'GROUP' : 'PAYMENT',
					'DEFAULT' : {
						'PROVIDER_KEY' : 'PAYMENT',
						'PROVIDER_VALUE' : 'ACCOUNT_NUMBER'
					}
				},
				"PAYMENT_SHOULD_PAY" : {
					"NAME" : 'Сумма оплаты',
					'SORT' : 600,
					'GROUP' : 'PAYMENT',
					'DEFAULT' : {
						'PROVIDER_KEY' : 'PAYMENT',
						'PROVIDER_VALUE' : 'SUM'
					}
				},
				"PS_CHANGE_STATUS_PAY" : {
					"NAME" : 'Автоматическая смена статуса оплаты',
					'SORT' : 700,
					"INPUT" : {
						'TYPE' : 'Y/N'
					},
				},
				"PAYMENT_BUYER_ID" : {
					"NAME" : 'Код покупателя',
					'SORT' : 1000,
					'GROUP' : 'PAYMENT',
					'DEFAULT' : {
						'PROVIDER_KEY' : 'ORDER',
						'PROVIDER_VALUE' : 'USER_ID'
					}
				}
			}
		}
	},
	function(result)
	{
		if(result.error())
			console.error(result.error());
		else
			console.info("Обработчик добавлен с ID " + result.data());
	}
);

Пример 3

Начиная с версии 21.700.0 модуля sale добавлены новые сценарии оплаты:

• Форма
• iFrame
• Checkout

Форма

При добавлении обработчика в SETTINGS нужно передать FORM_DATA (как в примерах выше). Способ подходит если от покупателя ничего не нужно запрашивать, либо запрашивается небольшой набор данных.

Поля формы автоматически выводятся в соответствии с дизайном страницы оплаты.

Данные формы (значения FIELDS из FORM_DATA) будут отправлены на ACTION_URI.

iFrame

При добавлении обработчика в SETTINGS нужно передать IFRAME_DATA (вместо FORM_DATA). По адресу из ACTION_URI должна располагаться страница, которая будет загружена в iframe на сайт продавца.

При загрузке iframe через метод Window.postMessage() на ACTION_URI будут переданы следующие данные:

• BX_SYSTEM_PARAMS:
  • RETURN_URL- текущая страница;
  • PAYSYSTEM_ID - идентификатор платежной системы;
  • PAYMENT_ID - идентификатор оплаты;
  • SUM - сумма платежа;
  • CURRENCY - валюта.
• BX_COMPUTED_STYLE (стили родительского элемента iframe, полученные методом window.getComputedStyle()
• значения FIELDS из IFRAME_DATA

Получить значения в iframe можно через обработчик события message, например:

//js
document.addEventListener("DOMContentLoaded", function() {
	window.addEventListener("message", function (event) {
		// получение данных от сайта (от платёжной системы)
		var paymentData = event.data;

		// работа с BX_SYSTEM_PARAMS
		if (paymentData.BX_SYSTEM_PARAMS)
		{
			// ...
		}

		// использование стилей сайта
		if (paymentData.BX_COMPUTED_STYLE)
		{
			document.body.style.background = paymentData.BX_COMPUTED_STYLE.background;
			document.body.style.color = paymentData.BX_COMPUTED_STYLE.color;
		}
	}, false);
});

По умолчанию ширина iframe - 100% родительского элемента, а высота - 350px.

Размеры iframe можно изменить. Для этого нужно из iframe передать высоту и/или ширину на сайт продавца. Например:

//js
document.addEventListener("DOMContentLoaded", function() {
	var size = {
		width: document.body.scrollWidth,
		height: document.body.scrollHeight
	};

	// отправка данных на сайт продавца
	parent.postMessage(size, "*");
});

width и height зарезервированные названия переменных и на сайте продавца обрабатываются только они.

Checkout

При добавлении обработчика в SETTINGS нужно передать CHECKOUT_DATA (вместо FORM_DATA).

По адресу из ACTION_URI должен располагаться скрипт, который обработает полученные данные, создаст оплату и вернёт идентификатор созданной оплаты и url страницы оплаты.

На ACTION_URI будут передаваться данные для оплаты:

• BX_SYSTEM_PARAMS:
  • RETURN_URL - текущая страница;
  • PAYSYSTEM_ID - идентификатор платежной системы;
  • PAYMENT_ID - идентификатор оплаты;
  • SUM - сумма платежа;
  • CURRENCY - валюта.
• значения FIELDS из CHECKOUT_DATA

В ответ на запрос к ACTION_URI, скрипт должен вернуть идентификатор созданной оплаты и url страницы оплаты.

Например:

//php
// ... код обработки полученных данных и создания оплаты

$result = [
	'PAYMENT_URL' => '', // url страницы оплаты
	'PAYMENT_ID' => '', // идентификатор оплаты
];

header('Content-Type:application/json; charset=UTF-8');
echo json_encode($result);

Покупатель перейдёт на ссылку из PAYMENT_URL автоматически или по клику ну кнопку "Купить".

C версии sale 22.200.0 можно вернуть массив ошибок в ключе PAYMENT_ERRORS. Ошибки менеджер увидит в таймлайне и может увидеть на странице оплаты (зависит от используемого шаблона).

Пример:

//php
// ... код обработки полученных данных и создания оплаты

$result = [
	'PAYMENT_ERRORS' => [
		'Some user custom error',
		'Some error more',
	]
];

header('Content-Type:application/json; charset=UTF-8');
echo json_encode($result);

Если ничего не возвращать, то будет использоваться ошибка по умолчанию: Ошибка регистрации заказа в платёжной системе (Error registering order in payment system)

Возможные значения