Проведение платежей через ArtPay.

  1. Предварительная настройка магазина.
  2. Этапы осуществления платежа.
  3. Формирование подписи.
  4. Примеры скриптов.
  5. Упрощенное подключение.
  6. API ArtPay.

Предварительная настройка магазина.

Перед началом работы с платежным шлюзом магазин настраивает параметры для выборов способов взаимодействия.

> > > > > > > >
Параметры настройки магазина
Название Тип Возможные значение
ap_storeid Идентификатор точки обслуживания
secret1 Ключевая фраза для подписи запросов магазина.
secret2 Ключевая фраза для подписи ответов шлюза.
algo Алгоритм шифрования. sha256|sha512
success url Адрес на который будет осуществлен переход в случае успешного платежа.
cancel url Адрес на который будет осуществлен переход в случае отказа от платежа/неудачной оплаты.
result url Адрес который будет вызван шлюзом в случае успешного платежа (уведомление о платеже).
success method Метод с помощью которого будет вызван success url. GET|POST
cancel method Метод с помощью которого будет вызван cancel url. GET|POST
result method Метод с помощью которого будет вызван result url. В случае значения MAIL - вызов result url осуществлен не будет. Вместо этого будет отправлено email уведомление. GET|POST|MAIL
success data format Формат данных передаваемых на success url. row|json
cancel data format Формат данных передаваемых на cancel url. row|json
result data format Формат данных передаваемых на result url (не имеет смысла при result method = MAIL)s. row|json

Этапы осуществления платежа.

  1. Инициализация платежа
  2. Переход пользователя от магазина на платежный шлюз
  3. Осуществление платежа/отказ от оплаты
  4. Возвращение в магазин

Инициализация платежа.

Магазин осуществляет POST или GET запрос на платежный шлюз по адресу https://engine.artpay.by/create/ (при использовании тестового режима: https://gateway-sandbox.artpay.by/create/ ) со следующими обязательными и опциональными полями:

Note При использовании тестового режима данные карты не проверяются. Средства с карты не списываются.
Параметры инициализации платежа
Название Тип Обязательность Значение Пример
ap_storeid String(1..30) Да Идентификатор точки обслуживания. 43434
ap_order_num Int64 Да Номер заказа. 123
ap_client_dt Int32 Да Дата и время: UNIX-время.
Сервер проверять, чтобы дата и время отличалось не более чем на 12 часов от даты и времени на сервере
1466602065
ap_amount Double Да Сумма платежа 12.10
ap_currency String(3..3) Да Цифровой трехсимвольный код валюты либо его буквенное обозначение согласно ISO4271. BYR|USD|EUR|RUR
ap_invoice_desc String (max 2500) Да Краткое описание приобретаемых товаров или оказываемых услуг. Холодильник
ap_signature String (32…512) Да Хеш-Подпись. ac9afb894a07a92fde3bc8638f475b1e3d6ca6f1780d1a711f11ba77f61236579
ap_lang String(2..2) Нет Язык пользовательского интерфейса. Принимает значения (ISO 639-1). Если выбранный язык не поддерживается, то используется русский. ru|en|pl
ap_test Boolean Нет Уведомляет сервер об использовании тестового режима. В случае, если значение параметра установлено в «1» или «true», возможно использование только тестового платежного шлюза.
При отсутствии в запросе, по умолчанию, параметр принимает значение «0» или «false» (реальный режим).
1|0
up_... String (1..1024) Нет Набор пользовательских параметров.
Разрешается добавлять до 16 пользовательских параметров с любыми именами, начинающимися с префикса «up_» (например, «up_any_param»). Данные параметры не обрабатываются и не учитываются в платежной системе при оплате, но передаются предприятию (точке обслуживания) после успешного выполнения операции в уведомлении. Пользовательские параметры учитываются при расчете хеш-подписи.
up_any_param=success
Note Пример формы для вызова инициализации платежа.
	<form method="POST" action="https://engine.artpay.by/create/">
		<input type="hidden" name="ap_storeid" value="57003"/>  
		<input type="hidden" name="ap_order_num" value="1234"/>  
		<input type="hidden" name="ap_amount" value="1000"/>  
		<input type="hidden" name="ap_currency" value="BYN"/>  
		<input type="hidden" name="ap_client_dt" value="1466602065"/>
		<input type="hidden" name="ap_invoice_desc" value="Телевизор марки Горизонт"/>   
		<input type="hidden" name="ap_test" value="0"/>  
		<input type="hidden" name="ap_signature" value="ac9afb894a07a92fde3bc8638f475b1e3d6ca6f1780d1a711f11ba77f612365798798bc9b99"/>  
		<input type="submit" value="Оплатить">
	</form>

Переход пользователя от магазина на платежный шлюз.

В случае корректности параметров Шлюз создает платеж и отправляет посетителя на страницу платежа. Если заказ создать не удалось, пользователю будет показана страница с ошибкой.

Пример адреса для перенаправления пользователя

https://engine.artpay.by/1dd6-a5be-9077-1b80-e5da-ca81-1d0e-5726/
Note Пример ошибки создания заказа.

Осуществление платежа/отказ от оплаты.

На странице платежа пользователь вводит данные карты либо отказывается от платежа.

Note Пример платежной формы.

Возвращение в магазин

В зависимости от результата платежа пользователь будет возвращен:

  1. В случае успешного платежа на success url.
    При этом с помощью метода из success method будет осуществлена передача пераметров платежа в формате указаным в success data format Также будет осуществлен вызов result url, при этом методом result method будут переданы параметры для оповещения платежа в формате указаным в result data format.
    Если в качестве result method указан email - то уведомление о платеже будет отправлено по электронной почте.
  2. В случае отказа от платежа/невозможности платежа на cancel url.
    При этом с помощью метода из cancel method будет осуществлена передача пераметров платежа в формате указаным в cancel data format.
Note Пример адреса перенаправления пользователя после оплаты.
http://testshop.tld/success/?ap_storeid=57003&ap_order_num=776175&ap_test=true&up_btn_name=super%21&ap_signature=0bce514e3144eb3fa611f1827441703e9631bcd1a005f1d044266bae33b871cc6abd3d5006ed0a17c078f28d7d634fdc38
Параметры уведомления о платеже
Название Тип Обязательность Значение
ap_storeid String(1..30) Да Идентификатор точки обслуживания.
ap_order_num Int64 Да Номер заказа.
ap_operation_status Enum : cancel|success Да Результат операции. cancel - платеж отменен. success - платеж прошел успешно.
ap_signature String (32…512) Да Хеш-Подпись.
ap_test Boolean Нет Уведомляет магазин об использовании тестового режима.
up_... String (1..1024) Нет Набор пользовательских параметров.
Пример формы для вызова инициализации платежа.
Формат Пример
JSON {"ap_storeid":57003,"ap_order_num":776175,"ap_test":true,"ap_operation_status":"success","up_btn_name":"super","ap_signature":"0bce514e314ed0a17c078f28d7d634fdc3846b17aeb2f41bb511830c3a677e0dc"}
ROWs ap_storeid=57003&ap_order_num=776175&ap_test=true&ap_operation_status=cancel&up_btn_name=super%21&ap_signature=0bce514e3144eb3fac078f28d7d634fdc3846b17aeb2f41bb511830c3a677e0dc

Формирование подписи.

Хеш-сумма сообщения – последовательность байтов в шестнадцатиричном виде (0-9, A-F илиa-f), рассчитанная хеш-функцией, указанной в конфигурации магазина.
Применяемые алгоритмы: SHA512 – по умолчанию, SHA256.
Все поля сообщения в алфавитном порядке (сортировка по имени параметра) следования склеиваются в одну строку. Далее в конец строки добавляется секретное слово точки обслуживания (Secret1 для запроса или Secret2 для ответа). Символ «;» является разделителем между параметрами, в конце и начале строки разделитель не ставится;
По полученной на предыдущем этапе строке выбранной хеш-функцией рассчитывается хеш-сумма;
Результат расчета является значением данного параметра.
Сам порядок следования параметров в сообщении не регламентирован.
Содержимое поля ap_signature не помещается в строку, по которой производится расчет хеш-суммы.

Note Пример формирования подписи (PHP)
	function formSignature(/* array */ $data)
	{
		
		$string = null;
		uksort($data, 'strnatcmp');
		
		foreach ($data as $param => $value)
			$string .= $value . ';';
		
		$string .=  ARTPAY_SECRET1;
		$key =  hash(ARTPAY_HASH_METHOD, $string);
		
		return $key;
		
	}
Note Пример проверки подписи в ответе сервера (PHP)
	function checkSignature(/* array */ $data)
	{
		if (!isset($data['ap_signature']))
			return false;
		
		$addSignature = $data['ap_signature'];
		unset($data['ap_signature']);
			
		uksort($data, 'strnatcmp');
		$string =  implode(';', $data) . ';' . ARTPAY_SECRET2;
			
		return hash(ARTPAY_HASH_METHOD, $string) == $addSignature;
		
	}

Примеры PHP-скриптов для подключения магазина к платежному шлюзу

Note Скачать

Упрощенное подключение

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

  1. Взять скрипт artpay.php из примеров кода.
  2. Настроить конфигурационные константы в соответствии с настройками магазина.
    				define('ARTPAY_SHOP_ID',  'Идентификатор точки обслуживания');
    				define('ARTPAY_SECRET1', 'Ключевая фраза для подписи запросов магазина.');
    				define('ARTPAY_SECRET2', 'Ключевая фраза для подписи ответов шлюза.');
    				define('ARTPAY_HASH_METHOD', 'Алгоритм шифрования.');
    				define('ARTPAY_TEST_MODE', 'флаг тестового режима'); // 1 при использовании тестового режима, 0 - при реальном использовании
    			
  3. Разместить скрипт artpay.php в корне сайта (www-root).
  4. Разместить код кнопки предварительно заменив значения в фигурных скобках на требуемые для платежа. Внимание! Фигурные скобки нужно убрать!
    
    	<!-- artpay code start -->
    	<div>
    		<script type="text/javascript" src="https://static.artpay.by/js/artpay.js"></script>
    		<div class="artpay" data-artpay-id="{ИДЕНТИФИКАТОР ЗАКАЗА}" data-artpay-url="/artpay.php" data-artpay-amount="{СУММА ЗАКАЗА}" data-artpay-desc="{ОПИСАНИЕ ЗАКАЗА}"></div>
    	</div>
    	<!-- artpay code end -->
    	
    	
    	
Note Если неободимо дизайн кнопки может быть изменен с помощью css через описание html-класса artpay.

API ArtPay

Документация предоставляется по запросу.