sale.paysystem.handler.add

Scope: pay_system Права на выполнение: для всех

Описание

sale.paysystem.handler.add(
	fields
)

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

Параметры

Параметр	Описание	С версии
fields	Набор полей(массив вида `array("поле":"значение"[, ...]))`, содержащий значения, описывающие обработчик. Доступные поля: NAME - Название обработчика CODE - Уникальный код обработчика в системе SETTINGS - Настройки обработчика SORT - Сортировка

Примеры

Пример 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());
	}
);

Примечание: Если передавать и FIELDS, и PARAMS, то будет использоваться только FIELDS.

Пример 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)

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

Возможные значения PROVIDER_KEY
ORDER	Параметры
PROPERTY	Свойства счета
PAYMENT	Оплата
USER	Пользователь
VALUE	Значение типа строка
Y\N	Чекбокс

Возможные значения PROVIDER_VALUE
ORDER	ID: ID (для счетов соответствует ID счета), ACCOUNT_NUMBER: Номер заказа (для счетов соответствует номеру счета), ORDER_TOPIC: Тема, DATE_INSERT: Дата заказа (для счетов соответствует дате счета), DATE_INSERT_DATE: Дата заказа (без времени) (для счетов соответствует дате счета (без времени)), DATE_BILL: Дата и время выставления, DATE_BILL_DATE: Дата выставления, DATE_PAY_BEFORE: Срок оплаты, SHOULD_PAY: Сумма счета (для счетов соответствует сумме счета), CURRENCY: Валюта, PRICE: Стоимость заказа (для счетов соответствует стоимости счета), PRICE_DELIVERY: Стоимость доставки, DISCOUNT_VALUE: Величина скидки, USER_ID: Код покупателя, PAY_SYSTEM_ID: Код платежной системы, DELIVERY_ID: Код службы доставки, TAX_VALUE: Налог, USER_DESCRIPTION: Комментарий
PAYMENT	ID: ID ACCOUNT_NUMBER: Номер оплаты, DATE_BILL: Дата и время выставления, DATE_BILL_DATE: Дата выставления (без времени), SUM: Сумма оплаты, CURRENCY: Валюта
USER	ID: Код покупателя, LOGIN: Логин, NAME: Имя, SECOND_NAME: Отчество, LAST_NAME: Фамилия, EMAIL: EMail, PERSONAL_PROFESSION: Профессия, PERSONAL_WWW: Персональный веб-сайт, PERSONAL_ICQ: Номер ICQ, PERSONAL_GENDER: Пол, PERSONAL_FAX: Номер факса, PERSONAL_MOBILE: Номер телефона, PERSONAL_STREET: Адрес, PERSONAL_MAILBOX: Почтовый ящик, PERSONAL_CITY: Город, PERSONAL_STATE: Штат, PERSONAL_ZIP: Индекс, PERSONAL_COUNTRY: Страна, WORK_COMPANY: Компания, WORK_DEPARTMENT: Отдел, WORK_POSITION: Должность, WORK_WWW: Сайт компании, WORK_PHONE: Рабочий телефон, WORK_FAX: Рабочий факс, WORK_STREET: Адрес компании, WORK_MAILBOX: Рабочий почтовый ящик, WORK_CITY: Город компании, WORK_STATE: Штат компании, WORK_ZIP: Индекс компании, WORK_COUNTRY: Страна компании