Регистрация

Вы можете ознакомиться и протестировать нашу платежную систему, воспользовавшись демо-версией.

Подключение интернет-магазина к Activepay

Скачать полную документацию в PDF

Существует две возможности подключения к Activepay через API.

Подключение Интернет-магазина по API с редиректом: пользователь после подтверждения покупки на сайте продавца перенаправляется на страницу Activepay. Далее покупатель выбирает способ оплаты и оплачивает покупку. После оплаты покупки производится перенаправление пользователя на страницу магазина, которая указывается владельцем в «Личном кабинете» во время подключения к системе. Мы рекомендуем этот способ владельцам малых и средних магазинов как простой и быстрый.

Подключение к Activepay через API: владелец Интернет-магазина будет принимать оплату товара или услуги на своей странице и передавать информацию о платеже в процессинговый центр Activepay скрытыми HTTP-запросами. Не все подключенные платежные системы поддерживают этот метод подключения. Мы рекомендуем этот способ владельцам крупных магазинов и сервисов.

При обоих случаях подключения общий алгоритм выглядит как:

  1. Управление передано процессингу ActivePay
  2. Проводится транзакция
  3. Магазин по специальным адресам (URL_OK и URL_FAILED) уведомляется о статусе транзакции
Также в обоих случаях используется один механизм безопасности: формирование hash-подписи. В панели управления для каждого подключения можно установить секретный ключ. На основе этого секретного ключа и других параметров запроса составляется специальная кодовая строка, которую проверит процессинг и которую должен проверить магазин в случае обратного запроса.

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

Безопасность и формирование подписи

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

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

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

  • метод запроса (GET или POST),
  • домен магазина,
  • путь на сайте процессинговой системы Activepay,
  • параметры (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 shop.ru /api/create/ urlencode(merchant_data)=urlencode(example_data)
&urlencode(merchant_description)=urlencode(example_description)&...

Конкретные примеры формирования подписи вы сможете посмотреть в готовых библиотеках подключения к Activepay.

Обратные вызовы

Вне зависимости от типа подключения, уведомление о статусе оплаты в случае ее завершения производится всегда одним способом: 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-структура из кода-описания ошибки (см. список ошибок)

Оба запроса всегда будут подписаны параметром signature. ВАЖНО: во избежание обманных запросов ВСЕГДА проверяйте signature этих запросов.

Подключение по API с редиректом

Для начала оплаты, необходимо переадресовать пользователя на страницу 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-запросом.

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

Параметры транзакции:
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. Кроме того, оба запроса будут содержать в себе подпись, которую необходимо проверить. Подпись формируется по алгоритму, описанному выше.

Подключение по API с прямой интеграцией

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

Готовые библиотеки подключения

Вы можете воспользоваться готовым решением для подключения вашего интернет-магазина к Activepay:

  • Пример подключения к ActivePay на PHP
  • Пример подключения к ActivePay на Perl
  • Пример подключения к ActivePay на Python
  • Пример подключения к ActivePay на C#

В ближайшее время будет доступен пример для Ruby.

Список ошибок

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

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'