VibeFox Adyen for WooCommerce — Помощь

Требования

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

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

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

Учётная запись Adyen: нужны название вашей учётной записи мерчанта Adyen, API-ключ и HMAC-ключ для каждой используемой среды (тестовой и рабочей), а для рабочих платежей — префикс рабочего URL. API-ключ относится к учётным данным API с ролями Checkout webservice и Merchant PAL webservice. HMAC-ключ создаётся для Standard webhook (см. раздел «Настройка»). Тестовая Customer Area находится по адресу ca-test.adyen.com, рабочая — по адресу ca-live.adyen.com. Тестовые и рабочие ключи разделены.

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

Установка

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

2. Нажмите Activate.

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

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

5. Введите учётную запись мерчанта, тестовый API-ключ и тестовый HMAC-ключ, а позже — рабочий API-ключ, рабочий HMAC-ключ и префикс рабочего URL.

6. В Adyen Customer Area (тестовой и рабочей) добавьте Standard webhook с URL, который показан в настройках плагина (см. раздел «Настройка»).

7. Включите Enable/Disable. Проверьте платёж при включённом Test mode, затем снимите отметку.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Adyen. Пока настройки текущего режима не заполнены, страница показывает Adyen is hidden at checkout until the test settings are complete (или рабочих настроек) и перечисляет, чего не хватает: Merchant account, API-ключа, HMAC-ключа и в рабочем режиме Live URL prefix. При сохранении HMAC-ключ, не являющийся шестнадцатеричным, и префикс рабочего URL с символами, отличными от букв, цифр и дефисов, отклоняются с ошибкой, а прежнее значение сохраняется.

Общие

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

Title: название способа оплаты, которое видят покупатели при оформлении заказа. По умолчанию: Adyen.

Description: текст под способом оплаты при оформлении заказа. По умолчанию: Pay securely via Adyen.

Учётная запись Adyen

API-ключи создаются в Adyen Customer Area в разделе Developers > API credentials. Заполните оба набора ключей; переключатель Test mode выбирает, какой из них используется.

Test mode: Use the Adyen test environment (no real money). Когда включено, платёжные ссылки и возвраты отправляются на checkout-test.adyen.com с тестовым API-ключом. По умолчанию: включено. Снимите отметку, чтобы принимать реальные платежи.

Merchant account: название вашей учётной записи мерчанта Adyen (а не учётной записи компании), например MyShopECOM. Обычно оно одинаково в тестовой и рабочей Customer Area.

Тестовые данные

Используются, пока включён Test mode.

Test API key: из тестовой Customer Area: Developers > API credentials > ваши учётные данные > API key.

Test HMAC key: из тестовой Customer Area: Developers > Webhooks > ваш Standard webhook > HMAC key (шестнадцатеричный). Обязательно: вебхуки без действительной подписи отклоняются.

Рабочие данные

Используются, когда Test mode выключен.

Live API key: из рабочей Customer Area: Developers > API credentials > ваши учётные данные > API key.

Live HMAC key: из рабочей Customer Area: Developers > Webhooks > ваш Standard webhook > HMAC key (шестнадцатеричный).

Live URL prefix: из рабочей Customer Area: Developers > API URLs, например 1797a841fbb37ca7-AdyenDemo из https://1797a841fbb37ca7-AdyenDemo-checkout-live.adyenpayments.com. Можно вставить весь URL: префикс будет взят из него при сохранении.

Вебхук

Заказы отмечаются оплаченными только вебхуками Adyen. В Customer Area (тестовой и рабочей) перейдите в Developers > Webhooks и добавьте Standard webhook с URL из этого раздела настроек. Он выглядит так: https://your-site/wc-api/adyg_adyen_webhook/. Выберите формат JSON, включите Generate HMAC key и скопируйте ключ в Test HMAC key или Live HMAC key. Среда каждого уведомления определяет, какой HMAC-ключ используется. Вебхуки без действительной подписи отклоняются, и Adyen повторяет их позже. Без вебхука заказы остаются в статусе Pending payment.

Плагин обрабатывает следующие события:

AUTHORISATION: платёж авторизован (заказ оплачивается после проверки суммы) или отклонён (ожидающий заказ переходит в статус Failed).

CAPTURE: платёж списан; добавляется примечание.

CAPTURE_FAILED: списание не прошло; оплаченный заказ переводится в статус On hold.

CANCELLATION: платёж по этому заказу отменён в Adyen; заказ отменяется.

REFUND: возврат подтверждён или не прошёл; добавляется примечание.

REFUND_FAILED: возврат не прошёл; примечание предупреждает, что деньги не возвращены.

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

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

Order status after payment: статус заказа, который устанавливается после успешной оплаты, одним изменением статуса.

Processing: стандартное значение WooCommerce (по умолчанию). Виртуальные загружаемые заказы завершаются автоматически.

Completed: каждый оплаченный заказ становится Completed.

On Hold: каждый оплаченный заказ ждёт вашей ручной проверки.

Debug log: Log API calls and webhook events записывает в WooCommerce > Status > Logs, источник wcp_adyen_gateway. Ошибки записываются всегда. В журналах никогда не содержатся API-ключи, HMAC-ключи или персональные данные покупателя. По умолчанию: выключено.

Delete data on uninstall: Delete the plugin settings and Adyen order meta (PSP references) when the plugin is deleted. По умолчанию: выключено.

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

Покупатель выбирает способ оплаты (по умолчанию Adyen) и оформляет заказ. Плагин создаёт платёжную ссылку Adyen на сумму заказа в валюте заказа и отправляет покупателя на страницу оплаты Adyen. Там покупатель платит любым способом, включённым в вашей учётной записи Adyen. Адрес e-mail, имя и страна из платёжных данных покупателя и язык магазина передаются в Adyen; в платеже отображаются Order # и номер заказа.

После оплаты покупатель возвращается на страницу «Заказ получен» вашего магазина. Само возвращение не отмечает заказ оплаченным: заказ отмечается оплаченным, только когда Adyen подтвердит его подписанным вебхуком AUTHORISATION и сумма и валюта совпадут с заказом.

Если платёж отклонён, заказ переходит в статус Failed, и покупатель может попробовать снова. Когда покупатель начинает новый платёж по тому же заказу, например со страницы Pay for order, предыдущая платёжная ссылка становится недействительной, поэтому по ней тоже нельзя заплатить.

Если платёжную ссылку создать не удаётся, покупатель видит сообщение Payment could not be initiated. Please try again or choose another payment method. Причина добавляется в примечания к заказу. Если настройки не заполнены, покупатель видит сообщение Payment gateway is not configured properly. Please contact the store administrator.

Для валют без десятичных знаков, таких как JPY, KRW, IDR или VND, задайте WooCommerce > Settings > General > Number of decimals равным 0. Иначе сумма округляется до целой единицы.

Способ оплаты работает в классическом оформлении заказа и в блоке «Оформление заказа». Он совместим с High-Performance Order Storage (HPOS) WooCommerce.

В плагине нет подписок и регулярных платежей, сохранённых карт, полей для карт на сайте (Drop-in или Components), кнопок списания или отмены в WooCommerce и базовой аутентификации для вебхуков.

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

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

Pending payment: платёжная ссылка создана, и Adyen ещё не подтвердил платёж. Примечание к заказу показывает платёжную ссылку, сумму и среду (тестовую или рабочую).

Processing, Completed или On Hold: платёж авторизован. Статус соответствует настройке Order status after payment. Примечание к заказу показывает сумму, PSP reference и способ оплаты. ID транзакции — это Adyen PSP reference.

On hold after payment: Adyen подтвердил сумму или валюту, отличные от итога заказа. Примечание к заказу показывает обе величины, а заказ не отмечается оплаченным. Оплаченный заказ также переводится в On hold, если списание не прошло, потому что деньги не были получены. Проверьте платёж в Customer Area.

Failed: платёж отклонён. Оплаченные, находящиеся в On hold и отменённые заказы не меняются из-за отклонённого платежа.

Cancelled: платёж по этому заказу отменён в Adyen.

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

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Adyen. Поддерживаются полные и частичные возвраты. Возврат отправляется в ту среду и на ту учётную запись мерчанта, где прошёл платёж, поэтому API-ключ этой среды должен быть задан. Adyen обрабатывает возвраты асинхронно: запрос отмечается в заказе, а окончательный результат добавляется примечанием вебхуком REFUND или REFUND_FAILED. Если Adyen не принимает запрос, WooCommerce показывает ошибку, и возврат не записывается. При ручном списании в Adyen возвращать можно только списанные платежи.

Возвраты, сделанные в Adyen Customer Area, приходят вебхуком и добавляются в примечания к заказу. Они автоматически не записываются как возвраты WooCommerce.

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

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

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

Без активного ключа Adyen не показывается покупателям при оформлении заказа. Если оплата всё же начата, покупатель видит сообщение This payment method is not available. Please choose another one. Менеджеры магазина, вошедшие в систему, по-прежнему видят способ оплаты с пометкой (unlicensed — visible to admins only), чтобы вы могли настроить и протестировать плагин до покупки ключа. Напоминание появляется на странице Plugins и на страницах WooCommerce. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а возвраты работают.

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

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

Adyen не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и настройки текущего режима заполнены: Merchant account, API-ключ и HMAC-ключ этого режима, а в рабочем режиме — Live URL prefix. Страница настроек показывает, чего не хватает.

Оплата прошла, но заказ остаётся в статусе Pending payment: вебхук не работает. В Customer Area той среды, которую вы используете (тестовой или рабочей), проверьте, что Standard webhook существует, что его URL точно совпадает с показанным в настройках и что выбран формат JSON. Проверьте, что HMAC-ключ этого вебхука вставлен в нужное поле (Test HMAC key или Live HMAC key). При неверном или отсутствующем HMAC-ключе плагин отвечает HTTP 401, и Adyen повторяет доставку позже, поэтому после исправления ключа заказ обновится автоматически. В журнале появится Webhook rejected: invalid HMAC signature или сообщение, что HMAC-ключ не настроен.

Webhook answers busy, retry later: заказ в этот момент обрабатывала другая доставка. Adyen повторит вебхук автоматически.

Ошибка при сохранении HMAC-ключа: поле должно содержать шестнадцатеричный HMAC-ключ из Customer Area. Прежнее значение сохранено.

Покупатель видит Payment could not be initiated: откройте примечания к заказу или включите Debug log и посмотрите в WooCommerce > Status > Logs, источник wcp_adyen_gateway. Проверьте API-ключ, учётную запись мерчанта и в рабочем режиме префикс рабочего URL.

Заказ в статусе On hold после оплаты: прочитайте примечание к заказу. Сумма или валюта, подтверждённые Adyen, не совпали с заказом, либо списание не прошло. Причиной может быть и настройка Order status after payment.

Возврат не проходит: у заказа должен быть Adyen PSP reference, который приходит с вебхуком AUTHORISATION. Должны быть заданы учётные данные среды, в которой прошёл платёж. При ручном списании возвращать можно только списанные платежи.

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

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить плагин, деактивируйте его и удалите на странице Plugins. Лицензионный ключ и статус лицензии этого плагина всегда удаляются. Настройки платёжного шлюза и данные Adyen, сохранённые в заказах (PSP references, платёжные ссылки, обработанные события), удаляются, только если была включена опция Delete data on uninstall. Иначе они сохраняются для повторной установки. Существующие заказы сохраняют свои примечания об оплате и ID транзакций.

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