Интеграция с редиректом

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

Помните, что подключения производятся для каждого из них отдельно: все ссылки на ID подключения далее по тексту относятся к цифре, которую вы можете увидеть рядом с названием магазина. Вы можете иметь несколько магазинов и, соответственно, несколько разных подключений.

Полная последовательность шагов для оплаты этим способом:

1. Магазин формирует URL с набором GET-параметров, включающих ID подключения и сумму платежа (полный список параметров далее по тексту)
2. Пользователь, переходя по этому адресу, попадает на платежную страницу ActivePay
3. Система проводит человека по всем шагам оплаты, начиная с выбора платежной системы
4. Когда платеж завершен система переадресует человека обратно в магазин
5. Как только платеж отменяется или успешно завершается, система уведомляет магазин отдельным фоновым HTTP-запросом со специальной подписью. По результатам именно этого запроса магазин считает оплату успешной, или отмененной.

Чтобы подключить данный способ взаимодействия, в настройках нужного магазина, выберите "HTTP-запрос" в поле "Способ уведомления о завершенной транзакции". Также необходимо заполнить два поля: "URL OK" и "URL FAILED".

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

Редирект покупателя в систему и обратно

Для начала оплаты, необходимо переадресовать пользователя на страницу ActivePay по адресу:

https://activepay.ru/merchant_pages/create/

сообщив системе следующие GET-параметры:

merchant_data	char(66)	произвольная строка данных, которая вернется сервису при обратном запросе как в случае успеха, так и в случае неудачи
merchant_description	char(100)	текстовое описание покупки, которое увидит пользователь
amount	decimal(15,2)	сумма, которую необходимо получить с покупателя
redirect_url_ok	char(200)	адрес, на который попадет пользователь по окончанию продажи в случае успеха. Данный параметр служит только для визуального завершения процесса. О факте успешной оплаты вы будете дополнительно уведомлены HTTP-запросом по адресу, указанному в панели управления
redirect_url_failed	char(200)	адрес, на который попадет пользователь по окончанию продажи в случае неудачи. Данный параметр служит только для визуального завершения процесса. О факте успешной оплаты вы будете дополнительно уведомлены HTTP-запросом по адресу, указанному в панели управления
merchant_contract	char(20)	ID вашего подключения к системе
signature	char(100)	подпись запроса. Алгоритм формирования подписи описан в соответствующем разделе.

В результате оплаты пользователь будет переадресован по одному из параметров: redirect_url_ok или redirect_url_failed, в зависимости от статуса оплаты. Факт успешной или неуспешной оплаты будет сообщен магазину дополнительно HTTP-запросом.

Мы разработали ряд готовых библиотек для распространенных языков программирования, которые уже содержат необходимый функционал для формирования правильного URL со всеми параметрами.

Пример: Оплата покупки в интернет-магазине.

Параметры транзакции:
ID подключения магазина к ActivePay	5
Номер транзакции магазина	54
В панели управления проставлены:
URL_OK	http://shop.ru/paid
URL_FAILED	http://shop.ru/failed

При нажатии кнопки "Оплатить" в магазине, человек адресуется на следующий адрес:

https://activepay.ru/merchant_pages/create/? 
					merchant_data=54 
					& 
					merchant_description=Покупка+овощей 
					& 
					redirect_url_ok=http://shop.ru/cart 
					& 
					redirect_url_failed=http://shop.ru/cart 
					& 
					merchant_contract=5 
					& 
					signature = ...

Как только оплата будет завершена, человек в браузере увидит страницу http://shop.ru/cart вне зависимости от результата.

При этом магазину уйдет дополнительный запрос на адрес http://shop.ru/paid если оплата была успешно завершена и http://shop.ru/failed если оплата не удалась.

Оба эти запроса будут содержать в себе параметр merchant_data = 54. Кроме того, оба запроса будут содержать в себе подпись, которую необходимо проверить. Подпись формируется по определенному алгоритму.

Прием HTTP-запросов о статусе

Сразу после того как оплата будет успешно произведена, система произведет обращение по адресу указанному в поле "URL OK" в настроках магазина. Если транзакция отменилась, обращение произойдет к адресу "URL FAILED". Оба этих обращения будут подписаны: во избежание мошенничества ВСЕГДА проверяйте подпись в обращениях по этим адресам. Подпись гарантирует, что обращение производит именно система.

Запрос на URL_OK содержит следующие параметры:

• result — 'success'
• payment_id — внутренний ID транзакции
• merchant_data — произвольная строка данных, которая была передана сервису при старте запроса

Запрос на URL_FAILED содержит следующие параметры:

• result — 'failed'
• payment_id — внутренний ID транзакции
• merchant_data — произвольная строка данных, которая была передана сервису при старте запроса
• errors — JSON-структура из кода-описания ошибки (см. список ошибок)

Алгоритм формирования подписи

Для проведения взаимодействия с системой все запросы необходимо подписывать по определенному алгоритму. Точно так же все запросы, приходящие от ActivePay будут подписаны ровно по этому же алгоритму.

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

В формировании подписи используются следующие элементы:

• метод запроса (GET или POST),
• домен системы, к которому вы обращаетесь (например activepay.ru),
• путь на сайте процессинговой системы Activepay (например /api/create/),
• параметры (query string),

которые передаются в соответствующем запросе.

Параметры должны быть отсортированы по ключу в алфавитном порядке и разделены знаком «&». Ключ и значение должны быть закодированы функцией URL-encode.

Строка для формирования подписи собирается в одну строку из перечисленных выше элементов, разделенных символом переноса строки (\n). Далее шифруется алгоритмом hmac с применением SHA1 и секретного ключа, который задается в «Личном кабинете» в настройках конкретного магазина. Полученные данные, в свою очередь, кодируются с помощью base64.

Мы разработали ряд готовых библиотек для распространенных языков программирования, которые уже содержат необходимый функционал для формирования подписи.

Пример:

При запросе

GET https://activepay.ru/api/create/?merchant_data=example_data&merchant_description=example_description&amount=54 

хэшированию и перекодировке в base64 подлежит следующая строка:

GET
activepay.ru
/api/create/
urlencode(merchant_data)=urlencode(example_data)&urlencode(merchant_description)=urlencode(example_description)&...

Коды ошибок

Полный список ошибок находится в процессе подготовки и появится в ближайшее время.

400 ValidationError 'Argument "%s" validation error: %s'
400 ArgumentOutOfRangeError '%s value (%s) is out of range%s%s'
400 ArgumentRequiredError 'Argument "%s" is required'
400 MultipleObjectsReturnedError 'Multi objects were returned for %s, parameters: "%s"'
400 NotSupportedError '%s "%s" is not supported%s'
403 InvalidSignatureError 'Signature is missed or invalid'
403 MerchantContractIsBlockedError 'Merchant contract is blocked'
404 NotFoundError '%s "%s" not found'
409 IllegalStateError '%s "%s" has state "%s" which is illegal for requested action'