VibeFox Adyen for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

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

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

Установка

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

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

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

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

5. В личном кабинете Adyen (тестовом и рабочем) добавьте Standard webhook с URL, который показан в разделе Webhook модуля (см. раздел «Настройка»).

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

При установке модуль создаёт статус заказа Adyen payment on hold. PrestaShop включает способ оплаты для валют, стран и групп клиентов, которые активны в этот момент. Проверьте и измените их в Payment > Preferences; страны, которые вы добавите позже, нужно отметить там же.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Adyen Gateway > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Пока настройки текущего режима не заполнены, страница показывает Adyen is hidden at checkout until the test settings are complete (или рабочих настроек) и перечисляет, чего не хватает: Merchant account, API-ключ, HMAC-ключ и в рабочем режиме Live URL prefix. Пока включён тестовый режим, страница показывает Test mode is on: payment links and refunds go to the Adyen test environment, no real money. При сохранении HMAC-ключ, который не является шестнадцатеричным, и префикс рабочего URL с символами, отличными от букв, цифр и дефисов, не сохраняются: предупреждение называет поле, а прежнее значение остаётся.

Adyen

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

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

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

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

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

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

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

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

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

Test API key: из тестового личного кабинета: Developers > API credentials > ваши учётные данные > API key.

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

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

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

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

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

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

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

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

Webhook

Заказы создаются только вебхуками Adyen. В личном кабинете (тестовом и рабочем) откройте Developers > Webhooks и добавьте Standard webhook с URL, который показан в поле Webhook URL в этом разделе. При включённых «красивых» URL он выглядит так: https://your-shop/module/wcp_adyen_gateway/webhook, возможно с кодом языка, например /en/. Копируйте URL точно так, как он показан в настройках, потому что Adyen не следует перенаправлениям. Выберите формат JSON, включите Generate HMAC key и скопируйте ключ в Test HMAC key или Live HMAC key.

Среда каждого уведомления определяет HMAC-ключ, а уведомление применяется только к платёжной ссылке, созданной в той же среде и для той же учётной записи мерчанта. Тестовое уведомление никогда не подтверждает рабочий платёж. Вебхуки без корректной подписи отклоняются с HTTP 401, и Adyen повторяет их позже. Без вебхука заказ не создаётся.

Модуль обрабатывает следующие события:

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

Advanced

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

Несовпадения суммы или валюты и неудачные списания всегда переводят заказ в статус Adyen payment on hold.

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

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

Delete data on uninstall: если включено, при удалении модуля удаляются его настройки, записи о платежах Adyen (референсы PSP, события вебхуков, возвраты) и журналы. Статус заказа Adyen payment on hold и заказы сохраняются. По умолчанию: выключено.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Adyen) и видит примечание You will be redirected to Adyen to complete the payment securely. После подтверждения модуль создаёт платёжную ссылку Adyen на сумму корзины в валюте корзины и отправляет покупателя на страницу оплаты Adyen. Там он платит любым способом, включённым в вашей учётной записи Adyen. E-mail, имя и страна выставления счёта покупателя, а также язык магазина передаются в Adyen, а платёж отображается как Cart # и номер корзины. На этом этапе заказа ещё нет.

После оплаты покупатель возвращается в ваш магазин. Сам возврат не создаёт и не оплачивает заказ: заказ отмечается оплаченным только после того, как Adyen подтвердит его подписанным вебхуком AUTHORISATION и сумма и валюта совпадут с корзиной. Если вебхук уже пришёл, покупатель видит стандартную страницу подтверждения заказа с Your payment with Adyen has been received. (или Your payment with Adyen has been received and is being reviewed by the store. для заказа на проверке). Если Adyen отменил платёж раньше, страница показывает Your Adyen payment was not completed. Please contact us about this order. Если вебхук ещё не пришёл, страница Payment confirmation показывает Your payment is being confirmed by Adyen. Your order will be created as soon as Adyen confirms the payment, and you will receive an e-mail. с кнопками Check again и Back to checkout — для покупателя, который не завершил оплату.

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

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

Разработчики могут изменить запрос платёжной ссылки с помощью хука actionAdygPaymentLinkRequest.

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

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

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

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

Payment accepted, Delivered or Adyen payment on hold: платёж авторизован. Статус зависит от Order status after payment. Платёж регистрируется с референсом PSP Adyen в качестве ID транзакции, а примечание показывает сумму, референс PSP и способ оплаты.

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

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

Refunded: платёж полностью возвращён через модуль.

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

Блок оплаты Adyen

На странице заказа есть блок Adyen payment с референсом PSP, платёжной ссылкой, учётной записью мерчанта и средой, статусом платежа, оплаченной и возвращённой суммой, значком Test mode для тестовых платежей, историей возвратов и Adyen notes — примечаниями, которые модуль добавляет к заказу (платёж авторизован, несовпадение суммы, дубликат оплаты, списание, отмена, результаты возвратов), сначала самые новые. Эти примечания — приватные сообщения заказа; PrestaShop 8.2 и 9 не показывают их в других местах страницы заказа.

Возвраты

В блоке Adyen payment введите сумму (подставляется сумма, которая ещё не возвращена), при желании причину, и нажмите Refund via Adyen. Подтвердите вопрос Refund this amount through Adyen? This cannot be undone. Поддерживаются полные и частичные возвраты. Нужно право редактировать заказы. Возвраты выполняются на сумму и в валюте, которые Adyen авторизовал, поэтому после несовпадения суммы или валюты можно вернуть не больше того, что покупатель фактически заплатил, а не сумму заказа. Возврат отправляется в ту среду и на ту учётную запись мерчанта, где прошёл платёж, поэтому API-ключ этой среды должен быть задан. Если Adyen не принимает запрос, блок показывает ошибку и возврат не регистрируется.

Adyen обрабатывает возвраты асинхронно: запрос добавляется в историю возвратов и примечания со статусом received, а окончательный результат приходит вебхуком REFUND или REFUND_FAILED. Неудачный возврат больше не считается возвращённым. Когда отправленные возвраты достигают оплаченной суммы, заказ переводится в статус Refunded. Частичный возврат статус не меняет. При ручном списании в Adyen возвращать можно только списанные платежи.

Модуль не создаёт кредитные накладные. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Adyen. Возвраты, сделанные в личном кабинете Adyen, приходят вебхуком и добавляются в примечания. Статус заказа и кредитные накладные автоматически не меняются.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Adyen Gateway — это первый блок на странице Modules > Module Manager > VibeFox Adyen Gateway > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки: Check now — проверить статус ещё раз, Change key — ввести другой ключ, Remove key — удалить ключ из этого магазина. Ниже находятся строка Product: presta-payment-adyen и ссылка 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.

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

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

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

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

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

Вебхук отвечает [rejected] HMAC key not configured: HMAC-ключ среды этого уведомления пуст. Вставьте его в настройки.

Вебхук отвечает [rejected] busy, retry later: корзину в этот момент обрабатывала другая доставка, либо заказ не удалось создать (например, модуль отключён). Adyen повторит вебхук автоматически. Причина записана в журнал.

URL вебхука показывает [rejected] POST required in the browser: это нормально. URL принимает только уведомления от Adyen.

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

Покупатель видит Payment could not be initiated: посмотрите поле Log на странице модуля (ошибки всегда записываются). Проверьте API-ключ, учётную запись мерчанта и, в рабочем режиме, префикс рабочего URL.

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

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

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Adyen Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete data on uninstall включено, удаляются настройки модуля, записи о платежах Adyen (референсы PSP, события вебхуков, возвраты) и журналы. Если выключено, всё это сохраняется для повторной установки, поэтому заказы, оплаченные раньше, можно вернуть. Статус заказа Adyen payment on hold всегда остаётся. Существующие заказы сохраняют свои примечания об оплате и ID транзакций.

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