СейлСервиСолюшенс -> +375 44 500-04-05, г. Минск, ул. Шафарнянская, 11, к. 419/8 (БЦ "Порт")

Документация

Проведение платежей через ArtPay. Информация для интеграторов.

Оглавление

  1. Предварительная настройка магазина.
  2. Этапы осуществления платежа.
  3. Формирование подписи.

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

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

Параметры настройки магазина.
Название Тип Возможные значение
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.dev-3c.by/create/ ) со следующими обязательными и опциональными полями:

При использовании тестового режима данные карты не проверяются. Средства с карты не списываются.

Параметры инициализации платежа.
Название Тип Обязательность Значение Пример
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. BYN|USD|EUR|RUB
ap_invoice_desc String (max 2500) Да Краткое описание приобретаемых товаров или оказываемых услуг. Холодильник
ap_signature String (32…512) Да Хеш-Подпись. ac9afb894a07a92fde3bc8638f475b1e3d6ca6f1780d1a711f11ba77f61236579
ap_lang String(2..2) Нет Язык пользовательского интерфейса. Принимает значения (ISO 639-1). Если выбранный язык не поддерживается, то используется русский. ru|en|pl|by
ap_test Boolean Нет Уведомляет сервер об использовании тестового режима. В случае если значение параметра установлено в "1" или "true", возможно использование только тестового платежного шлюза.
При отсутствии в запросе, по умолчанию, параметр принимает значение "0" или "false" (реальный режим).
1|0
up_... String (1..1024) Нет Набор пользовательских параметров.
Разрешается добавлять до 16 пользовательских параметров с любыми именами, начинающимися с префикса "up_" (например, "up_any_param"). Данные параметры не обрабатываются и не учитываются в платежной системе при оплате, но передаются предприятию (точке обслуживания) после успешного выполнения операции в уведомлении. Пользовательские параметры учитываются при расчете хеш-подписи.
up_any_param=success

Пример формы для вызова инициализации платежа.

<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="dab4a472561b49c355a80379f0a96a7efe2269bb7cc45b48ce9e587b6c2415de"/>
	<input type="submit" value="Оплатить">
</form>

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

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

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

https://engine.artpay.by/1dd6-a5be-9077-1b80-e5da-ca81-1d0e-5726/

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

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

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

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

  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.

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

http://testshop.tld/success/?ap_storeid=57003&ap_order_num=776175&ap_test=true&result=success&up_btn_name=super%21&ap_signature=dab4a472561b49c355a80379f0a96a7efe2269bb7cc45b48ce9e587b6c2415de
Параметры уведомления о платеже.
Название Тип Обязательность Значение
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":"ac9afb894a07a92fde3bc8638f475b1e3d6ca6f1780d1a711f11ba77f61236579"}
ROWs ap_storeid=57003&ap_order_num=776175&ap_test=true&ap_operation_status=cancel&up_btn_name=super%21&ap_signature=ac9afb894a07a92fde3bc8638f475b1e3d6ca6f1780d1a711f11ba77f61236579
Подключиться

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

Хеш-сумма сообщения – последовательность байтов в шестнадцатиричном виде (0-9, A-F илиa-f), рассчитанная хеш-функцией, указанной в конфигурации магазина.

Применяемые алгоритмы: SHA512 – по умолчанию, SHA256.

Все поля сообщения в алфавитном порядке (сортировка по имени параметра) следования склеиваются в одну строку. Далее в конец строки добавляется секретное слово точки обслуживания (Secret1 для запроса или Secret2 для ответа). Символ ";" является разделителем между параметрами, в конце и начале строки разделитель не ставится;
По полученной на предыдущем этапе строке выбранной хеш-функцией рассчитывается хеш-сумма;
Результат расчета является значением данного параметра.
Сам порядок следования параметров в сообщении не регламентирован.
Содержимое поля ap_signature не помещается в строку, по которой производится расчет хеш-суммы.

Пример формирования подписи (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;

	}

Пример проверки подписи в ответе сервера (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;

	}