VibeFox HyperPay for WooCommerce — Помощь

Требования

WordPress: 6.0 или новее.

WooCommerce: 8.0 или новее, установлен и активен. Без него плагин не активируется.

PHP: 8.0 или новее.

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

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

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

Установка

1. В WordPress откройте Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Также можно загрузить папку wcp_hyperpay_payment_gateway в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Payments > HyperPay > Manage или нажмите Settings под названием плагина на странице «Плагины».

4. Введите лицензионный ключ VibeFox в блок лицензии вверху страницы и нажмите Activate.

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

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

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

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > HyperPay. Над полями страница показывает Тестовый режим включён: платежи уходят в тестовую систему HyperPay, и реальные деньги не списываются. пока включён тестовый режим. Страница предупреждает, если не заполнены Access Token или Entity ID текущего режима (тогда способ оплаты не показывается при оформлении заказа), и если у текущего режима нет корректного ключа вебхука (тогда платежи подтверждаются, только когда покупатель возвращается в магазин). В списке способов оплаты шлюз помечен как требующий настройки, пока у текущего режима нет Access Token и Entity ID. При сохранении пробелы в учётных данных удаляются, а страница показывает ошибку, если ключ вебхука не является 64-символьным шестнадцатеричным ключом.

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: Enable Test Mode использует тестовую систему HyperPay (eu-test.oppwa.com) и тестовые учётные данные. Реальные деньги не списываются. Выключите режим, чтобы принимать настоящие платежи с рабочими учётными данными (eu-prod.oppwa.com). По умолчанию: включено.

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

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

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

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

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

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

Webhook

Вебхук сообщает вашему магазину о платежах, даже если покупатель закрыл браузер, не вернувшись в магазин. В панели управления HyperPay (Administration > Webhooks) добавьте вебхук для платежей с URL из этого раздела настроек. URL выглядит так: https://your-site/wp-json/hyperpay-p/v1/webhook. Затем скопируйте ключ расшифровки вебхука в Test Webhook Key или Live Webhook Key для того же режима.

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

Платёж

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

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

Дополнительно

Enable Logging: Log API requests and responses. Отладочная информация записывается в WooCommerce > Status > Logs, источник wcp_hyperpay_payment_gateway. Ошибки записываются всегда. Журналы не содержат данных карт, ключей и данных покупателей. По умолчанию: выключено.

Delete Data on Uninstall: Delete all plugin data when the plugin is uninstalled. Удаляет настройки и файлы журналов при удалении плагина. Данные HyperPay, сохранённые в заказах, остаются. По умолчанию: выключено.

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

Покупатель выбирает способ оплаты (по умолчанию Credit/Debit Card (HyperPay)) и нажимает Continue to payment. Заказ создаётся, и покупатель переходит на страницу Pay for order. Там плагин готовит платёжную сессию HyperPay на сумму заказа в валюте заказа и показывает виджет HyperPay с надписью Пожалуйста, завершите оплату ниже:. Виджет использует язык вашего сайта, если HyperPay его поддерживает. В тестовом режиме страница показывает Тестовый режим: используйте тестовую карту HyperPay, реальный платёж не будет выполнен. Покупатель вводит данные карты в виджете.

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

Если платёж не прошёл, покупатель возвращается на страницу Pay for order с сообщением: Ошибка оплаты: и причиной от HyperPay, Оплата не была завершена. Попробуйте ещё раз., или Нам пока не удалось подтвердить ваш платёж. Если с вас списаны деньги, заказ будет обновлён автоматически; в противном случае попробуйте ещё раз. Покупатель может снова оплатить на той же странице. Если виджет не удалось подготовить, покупатель видит короткое сообщение, например о том, что платёжный провайдер не принял некоторые платёжные данные, и кнопку Try Again. Подробности добавляются в примечания к заказу.

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

Способ оплаты работает в классическом оформлении заказа, в блоках «Корзина» и «Оформление заказа», а также на странице Pay for order. В тестовом режиме блок «Оформление заказа» показывает Тестовый режим: реальный платёж не будет выполнен. Совместим с WooCommerce High-Performance Order Storage (HPOS).

Плагин не поддерживает возвраты и отмены из WooCommerce, сохранённые карты и токенизацию, подписки, проверку домена для Apple Pay, отдельные Entity ID для каждого бренда, а также Tabby, Tamara и другие методы «купи сейчас, плати потом» (buy now, pay later).

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

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

Pending payment: покупатель ещё не оплатил, не завершил работу с виджетом или HyperPay ещё не подтвердил платёж.

Processing: подтверждён платёж с списанием или предавторизация списана. Заказы, содержащие только виртуальные скачиваемые товары, переходят в статус «Выполнен», принятый в WooCommerce по умолчанию. Примечание к заказу показывает код результата HyperPay, описание и ID платежа. ID транзакции — это ID платежа HyperPay. Если HyperPay отметил платёж для ручной проверки, примечание об этом сообщит; проверьте его в панели управления HyperPay до отправки.

On hold (pre-authorization): сумма зарезервирована. Спишите её действием заказа Capture HyperPay payment или в панели управления HyperPay; вебхук списания затем завершит заказ.

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

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

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

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

Списание

Действие заказа Capture HyperPay payment появляется у заказов на удержании с предавторизацией, которая ещё не списана. Оно списывает текущую сумму заказа за вычетом возвратов, уже записанных в WooCommerce, в том режиме, в котором была сделана предавторизация. После успешного списания заказ переходит в статус «Выполняется». Если HyperPay отклоняет списание, показываются код результата и описание, которые добавляются в примечания к заказу. Отмена (void) предавторизации выполняется в панели управления HyperPay.

Возвраты

Возвраты из WooCommerce не поддерживаются. Вернув платёж в панели управления HyperPay, зафиксируйте его в WooCommerce действием Refund manually. Возвраты и чарджбэки, выполненные в HyperPay, добавляются к заказу примечанием через вебхук; статус заказа не меняется.

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

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Payments > HyperPay. Вставьте ключ в поле License key и нажмите Activate. В блоке показывается статус, например дата, до которой лицензия активна, и ваш домен. Кнопка Check now проверяет статус снова, Change key позволяет ввести другой ключ, а Remove key удаляет его с этого сайта. Ссылка Manage licenses and domains in your account открывает ваш аккаунт на vibefox.net.

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

Без активного ключа HyperPay не показывается покупателям при оформлении заказа. Если оплата всё же начата, покупатель видит Этот способ оплаты недоступен. Выберите другой. Администраторы магазина, вошедшие в систему, по-прежнему видят способ оплаты с пометкой (unlicensed — visible to admins only), чтобы настроить и протестировать плагин до покупки ключа. Напоминание появляется на странице «Плагины» и на страницах WooCommerce. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а списания работают.

Когда лицензия истекает, плагин продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется в фоновом режиме.

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

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

Платёж прошёл, но заказ остаётся в статусе Pending payment: вебхук не работает, а покупатель не вернулся в магазин. В панели управления HyperPay проверьте, что платёжный вебхук существует для используемого режима, что его URL совпадает с показанным в настройках, и что его ключ расшифровки находится в поле ключа вебхука того же режима. Посмотрите WooCommerce > Status > Logs, источник wcp_hyperpay_payment_gateway.

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

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

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

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

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

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

Блок лицензии показывает ошибку: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите слот в аккаунте на vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжает работать по последнему известному статусу.

Для разработчиков: фильтр hyperpay_p_icon меняет значок способа оплаты.

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить его, деактивируйте и удалите плагин на странице Plugins. Лицензионный ключ и статус лицензии этого плагина всегда удаляются. Настройки шлюза, временные данные плагина и файлы журналов удаляются только если была включена опция Delete Data on Uninstall. Иначе они сохраняются для повторной установки. Данные HyperPay, сохранённые в заказах, всегда остаются. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

HyperPay — товарный знак его правообладателя. Этот плагин не связан с HyperPay и не одобрен HyperPay.