VibeFox HyperPay for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее с расширением OpenSSL (оно расшифровывает вебхуки). Без него модуль не устанавливается.

Учётная запись HyperPay: HyperPay выдаёт Access Token и Entity ID при подключении вашей учётной записи мерчанта. Тестовые и рабочие данные различаются. Также нужен платёжный вебхук в панели управления HyperPay и его ключ расшифровки (webhook key), который показан в разделе Administration > Webhooks (см. Настройка).

Данные карты: карта вводится только в виджете HyperPay, поэтому данные карты никогда не попадают на ваш сервер (PCI DSS SAQ A).

Лицензионный ключ VibeFox: приобретается на vibefox.net. Один ключ работает на одном домене.

Установка

1. В back office откройте Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. По завершении загрузки нажмите Configure или позже найдите VibeFox HyperPay Payment Gateway в списке модулей и нажмите Configure.

3. Введите лицензионный ключ VibeFox в поле License key блока лицензии вверху страницы Configure и нажмите Activate (см. Лицензионный ключ).

4. Введите тестовые Access Token, Entity ID и ключ вебхука, выданные HyperPay, и оставьте включённым Test Mode.

5. В панели управления HyperPay (Administration > Webhooks) добавьте платёжный вебхук с URL из раздела Webhook и скопируйте его ключ расшифровки в поле ключа вебхука того же режима.

6. Включите Enable/Disable, нажмите Save и проведите тестовую оплату тестовой картой HyperPay. Затем введите рабочие данные и выключите Test Mode.

При установке модуль создаёт три статуса заказа: Awaiting HyperPay payment, HyperPay payment authorized и HyperPay payment on hold. PrestaShop привязывает новый платёжный модуль к валютам, странам и группам клиентов, которые активны на этот момент. Страны, которые вы активируете позже, нужно разрешить в Payment > Preferences.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox HyperPay Payment Gateway > Configure. У каждого раздела своя кнопка Save, которая сохраняет всю страницу. Над полями страница показывает Test mode is on: payments go to the HyperPay test system and no real money is charged., пока включён тестовый режим. Она предупреждает, если не заполнены Access Token или Entity ID текущего режима (тогда способ оплаты не показывается в оформлении заказа), и если в текущем режиме нет действительного ключа вебхука (тогда платежи подтверждаются только при возврате покупателя в магазин). При сохранении пробелы удаляются из данных доступа, а страница предупреждает, если ключ вебхука не является 64-символьным шестнадцатеричным ключом.

HyperPay

Enable/Disable: Enable HyperPay Payment включает или выключает способ оплаты. По умолчанию: выключено.

Title: название, которое покупатель видит в оформлении заказа. Оно же сохраняется в заказе как название способа оплаты. По умолчанию: Credit/Debit Card (HyperPay). Обязательное поле.

Description: описание, которое покупатель видит в оформлении заказа. По умолчанию: Pay securely using your credit or debit card.

Данные доступа API

Access Token, Entity ID и ключ вебхука выдаёт HyperPay при подключении вашей учётной записи мерчанта. Тестовые и рабочие данные различаются. Ключ вебхука показан в панели управления HyperPay в разделе Administration > Webhooks.

Test Mode: использует тестовую систему HyperPay (eu-test.oppwa.com) и тестовые данные. Реальные деньги не списываются. Выключите режим, чтобы принимать реальные платежи с рабочими данными (eu-prod.oppwa.com). По умолчанию: включено. Пока режим включён, покупатели видят под способом оплаты Test mode: no real payment will be made.

Test Access Token: bearer-токен вашей тестовой учётной записи HyperPay.

Test Entity ID: Entity ID тестового платёжного канала.

Test Webhook Key: 64-символьный шестнадцатеричный ключ для расшифровки уведомлений вебхука тестовой системы.

Live Access Token: bearer-токен вашей рабочей учётной записи HyperPay.

Live Entity ID: Entity ID рабочего платёжного канала.

Live Webhook Key: 64-символьный шестнадцатеричный ключ для расшифровки уведомлений вебхука рабочей системы.

Сохранённые access tokens и ключи вебхуков больше не отображаются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить.

Очистка сохранённых секретов: отметьте токен или ключ и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

Webhook

Вебхук сообщает вашему магазину о платежах даже тогда, когда покупатель закрывает браузер до возврата в магазин. В панели управления HyperPay (Administration > Webhooks) добавьте вебхук для платежей с URL, который показан в поле Webhook URL в этом разделе. При ЧПУ-адресах он выглядит так: https://your-shop/module/wcp_hyperpay_payment_gateway/webhook, возможно, с кодом языка, например /en/. Копируйте URL точно так, как он показан в настройках. Затем скопируйте ключ расшифровки вебхука в поле Test Webhook Key или Live Webhook Key того же режима.

Вебхуки HyperPay зашифрованы (AES-256-GCM). Вебхук, который нельзя расшифровать вашими ключами, отклоняется. Обрабатываются только уведомления о платежах, и платёж должен принадлежать платёжной сессии одной из ваших корзин, созданной в том же режиме, что и ключ, которым он расшифрован. Тестовые уведомления HyperPay подтверждаются. Вебхук также сообщает о списаниях, реверсах, возвратах и чарджбэках, выполненных в панели управления HyperPay (см. Заказы и возвраты). Без вебхука платёж подтверждается только тогда, когда покупатель возвращается в магазин после оплаты.

Payment

Transaction Type: способ списания с карты.

Payment Brands: бренды, которые показываются в платёжном виджете: VISA, Mastercard, mada, American Express, STC Pay, Apple Pay. По умолчанию: VISA и Mastercard. Если не выбран ни один бренд, страница предупреждает, и виджет показывает VISA и Mastercard. Выбирайте только те бренды, которые HyperPay включил для вашего Entity ID; mada, STC Pay и Apple Pay часто используют собственную entity, которую этот модуль не поддерживает.

Advanced

Enable Logging: записывает запросы и ответы API в logs/hyperpay_p_debug.log.php в папке модуля. Файл нельзя открыть через веб. Ошибки и предупреждения записываются всегда. Журналы не содержат данных карт, ключей и данных покупателей. По умолчанию: выключено.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.

Delete Data on Uninstall: если включено, при удалении модуля удаляются настройки, таблица попыток платежей HyperPay и файлы журналов. Заказы и статусы заказов модуля сохраняются. По умолчанию: выключено.

Оформление заказа

На шаге оплаты покупатель выбирает способ оплаты (по умолчанию Credit/Debit Card (HyperPay)) и подтверждает заказ. Модуль готовит платёжную сессию HyperPay на сумму корзины в валюте корзины и открывает страницу HyperPay payment вашего магазина с виджетом HyperPay и надписью Please complete your payment below:. Виджет использует язык покупателя, если HyperPay его поддерживает. В тестовом режиме страница показывает Test mode: use a HyperPay test card, no real payment will be made. Покупатель вводит данные карты в виджете или переходит по ссылке Choose another payment method, чтобы вернуться в оформление заказа. На этом этапе заказа ещё нет. При перезагрузке страницы используется та же платёжная сессия в течение до 25 минут, пока корзина не меняется.

После оплаты покупатель возвращается в магазин. Модуль проверяет, что платёж принадлежит одной из платёжных сессий этой корзины, и запрашивает результат у HyperPay серверным запросом в том режиме, в котором была создана сессия. Заказ отмечается оплаченным только тогда, когда HyperPay подтвердит платёж: этим запросом или вебхуком. Сумма и валюта должны совпадать с корзиной. Если возврат и вебхук приходят одновременно, они обрабатываются по очереди, поэтому заказ никогда не создаётся дважды. Когда платёж подтверждён, заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа.

Если платёж не прошёл, покупатель возвращается в оформление заказа с сообщением: Payment failed: и причиной от HyperPay, Payment was not completed. Please try again. или We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. Корзина сохраняется, и покупатель может оплатить снова; каждая новая попытка получает новую платёжную сессию HyperPay. Если платёжную форму не удалось подготовить, покупатель остаётся в оформлении заказа с коротким сообщением, например о том, что платёжный провайдер не принял некоторые платёжные данные, или что платёжная форма недоступна из-за ошибки конфигурации платежей. Техническая причина записывается в журнал.

Суммы передаются с двумя знаками после запятой, как того требует API HyperPay. Для валют с тремя знаками после запятой (KWD, BHD, JOD, OMR) сумма корзины округляется до двух знаков.

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

Модуль не поддерживает возвраты и отмены из PrestaShop, сохранённые карты и токенизацию, подписки, проверку домена для Apple Pay, отдельные Entity ID для каждого бренда, а также Tabby, Tamara и другие методы «купи сейчас, плати потом».

Заказы и возвраты

Статусы заказа

No order yet: покупатель был направлен на страницу оплаты и не оплатил, платёж был отклонён или HyperPay ещё не подтвердил платёж. Существует только корзина.

Payment accepted: подтверждён платёж списанием или захвачена предавторизация. Платёж записывается с ID платежа HyperPay в качестве ID транзакции, а приватная заметка показывает код результата HyperPay, описание и ID платежа. Если HyperPay пометил платёж для ручной проверки, заметка это указывает; проверьте его в панели управления HyperPay перед отправкой.

HyperPay payment authorized: сумма зарезервирована предавторизацией. Спишите её в блоке HyperPay заказа или в панели управления HyperPay; вебхук списания затем переводит заказ в статус Payment accepted.

Awaiting HyperPay payment: HyperPay сообщил, что платёж ожидает обработки. Заказ переходит в статус Payment accepted, когда HyperPay подтвердит платёж.

HyperPay payment on hold: HyperPay сообщил сумму или валюту, отличные от корзины или заказа (например, корзина была изменена после открытия страницы оплаты), либо платёж пришёл после отмены заказа. Заметка объясняет причину. Проверьте платёж в панели управления HyperPay, затем выполните заказ или сделайте возврат платежа.

Canceled: предавторизация была отменена в панели управления HyperPay, и вебхук реверса отменяет авторизованный заказ.

Отклонённый результат никогда не меняет существующий заказ. Если для уже оплаченного заказа приходит ещё один успешный платёж, заказ не меняется. Заметка просит вас вернуть дубликат в панели управления HyperPay. Успешный платёж по возвращённому заказу только добавляет заметку.

Блок платежа HyperPay

На странице заказа показан блок HyperPay payment с ID платежа (и ID списания после списания), типом транзакции, ID платёжной сессии, ID транзакции мерчанта, суммой, отправленной в HyperPay, результатом и значком Test mode для тестовых платежей. Заметки модуля находятся в приватных сообщениях заказа.

Списание

Для заказа в статусе HyperPay payment authorized блок показывает Capture payment с суммой. Нажмите кнопку и подтвердите Capture the pre-authorized amount through HyperPay?. Списывается текущая сумма заказа в том режиме, в котором была сделана предавторизация, поэтому должны быть заполнены Access Token и Entity ID этого режима. Нужно право редактировать заказы; доступ к страницам модуля не требуется. После успешного списания заказ переходит в статус Payment accepted, а ID списания добавляется к платежу и заметкам. Если HyperPay отказывает в списании, показываются код результата и описание, они добавляются в заметки, а заказ остаётся авторизованным. Двойной щелчок не списывает деньги дважды. Отмена (void) предавторизации выполняется в панели управления HyperPay.

Возвраты

Возвраты из PrestaShop не поддерживаются, а стандартные кнопки возврата PrestaShop не возвращают деньги через HyperPay. Выполните возврат платежа в панели управления HyperPay и при необходимости зарегистрируйте его в PrestaShop как частичный возврат или кредитную накладную. Возвраты и чарджбэки, выполненные в HyperPay, вебхук добавляет в заказ как заметку; статус заказа не меняется.

Лицензионный ключ

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox HyperPay Payment Gateway — первый блок на странице Modules > Module Manager > VibeFox HyperPay Payment Gateway > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-hyperpay и ссылка Manage licenses and domains in your account, которая открывает вашу учётную запись vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока следуют языку бэк-офиса (включены английский и русский).

Если ключ не принят, блок указывает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения слота домена в вашей учётной записи нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: домене основного магазина, в том числе при мультимагазинной настройке. Удаление ключа из магазина не освобождает его слот домена. Освободите слот в своей учётной записи vibefox.net.

Без активного ключа HyperPay не показывается покупателям в оформлении заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Магазин PrestaShop не знает, что вы вошли в бэк-офис, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но нельзя протестировать в оформлении заказа. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а списания и возвраты работают.

Когда лицензия истекает, модуль продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется, пока вы работаете в бэк-офисе: раз в день в течение первых 14 дней после ввода ключа, затем раз в неделю. Cron-задание не нужно. При удалении или сбросе модуля лицензионный ключ и статус лицензии всегда удаляются.

Устранение неполадок

HyperPay не появляется в оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и в текущем режиме заполнены Access Token и Entity ID: тестовые — в тестовом режиме, рабочие — в рабочем. Страница настроек показывает предупреждение, если их нет. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: вебхук не работает, а покупатель не вернулся в магазин. В панели управления HyperPay проверьте, что платёжный вебхук существует для режима, который вы используете, что его URL точно совпадает с показанным в Webhook URL, и что его ключ расшифровки находится в поле ключа вебхука того же режима. Включите Enable Logging и посмотрите поле Log на странице модуля.

Вебхук отвечает Decryption failed: ключ вебхука принадлежит другому вебхуку или другому режиму. Скопируйте ключ заново из панели управления HyperPay.

Вебхук отвечает Webhook key not configured: не задан действительный ключ вебхука. Вставьте 64-символьный ключ в настройки. HyperPay повторит вебхук.

Вебхук отвечает Busy, retry later: заказ в этот момент обрабатывал другой запрос, либо заказ не удалось создать (например, потому что модуль выключен). HyperPay повторит вебхук. Причина указана в журнале.

В журнале появилось Webhook ignored: платёж не принадлежит корзине этого магазина или сделан в другом режиме. Тестовые и рабочие платежи разделяются.

URL вебхука в браузере показывает Method not allowed: это нормально. URL принимает только POST-запросы от HyperPay.

Платёжная форма не загружается: посмотрите журнал. Ошибка конфигурации обычно означает неверные Access Token или Entity ID для текущего режима. Сообщение о платёжных данных означает, что HyperPay не принял часть данных покупателя. Убедитесь, что выбранные Payment Brands включены для вашего Entity ID.

Заказ в статусе HyperPay payment on hold: прочитайте заметки заказа (см. Статусы заказа), проверьте платёж в панели управления HyperPay, затем выполните заказ или сделайте возврат платежа.

Списание не удаётся: прочитайте код результата и описание в блоке и заметках. Списание отправляется в режиме предавторизации, поэтому данные доступа этого режима должны быть заполнены; иначе блок сообщит, что Access Token / Entity ID этого режима пусты.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox HyperPay Payment Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete Data on Uninstall включено, удаляются настройки, таблица попыток платежей HyperPay и файлы журналов. Если выключено, всё сохраняется для повторной установки позже. Статусы заказа Awaiting HyperPay payment, HyperPay payment authorized и HyperPay payment on hold всегда сохраняются. Существующие заказы сохраняют свои платёжные заметки и ID транзакций.

HyperPay является товарным знаком своего владельца. Этот модуль не аффилирован с HyperPay и не одобрен им.