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 (або live-налаштування) і перелічує, чого бракує: 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 повторює їх пізніше. Без вебхука замовлення не створюється.

Модуль обробляє такі події:

Інші події додаються до приміток замовлення. Повідомлення, які не стосуються кошика цього магазину, наприклад тестова кнопка в особистому кабінеті, приймаються і ігноруються. Вебхук працює, поки магазин перебуває в режимі обслуговування, і не блокується обмеженням за країною вашого магазину.

Додатково

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.