VibeFox Adyen for WooCommerce — Допомога

Вимоги

WordPress: 6.0 або новіша.

WooCommerce: 7.0 або новіша, встановлений і активний. Плагін не активується без нього.

PHP: 8.0 або новіша.

Обліковий запис Adyen: потрібні назва вашого облікового запису мерчанта Adyen, ключ API і ключ HMAC для кожного середовища, яке ви використовуєте (тестового і робочого), а для платежів у робочому режимі — префікс робочого URL. Ключ API належить обліковим даним API з ролями Checkout webservice і Merchant PAL webservice. Ключ HMAC генерується для стандартного вебхука (див. розділ «Налаштування»). Тестовий 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. У Customer Area Adyen (тестовому і робочому) додайте Standard webhook з адресою, яку показано в налаштуваннях плагіна (див. розділ «Налаштування»).

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 створюються в Customer Area Adyen у розділі 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 з адресою, яку показано в цьому розділі налаштувань. Вона має вигляд https://your-site/wc-api/adyg_adyen_webhook/. Оберіть метод JSON, увімкніть Generate HMAC key і скопіюйте ключ у Test HMAC key або Live HMAC key. Середовище кожного повідомлення визначає, який ключ HMAC використовується. Вебхуки без дійсного підпису відхиляються, і Adyen повторює їх пізніше. Без вебхука замовлення залишаються в статусі Pending payment.

Плагін обробляє такі події:

AUTHORISATION: платіж авторизовано (замовлення оплачується після перевірки суми) або відхилено (замовлення в статусі Pending payment переходить у статус 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. Інакше сума буде округлена до цілої одиниці.

Спосіб оплати працює в класичному оформленні замовлення та в блоці Checkout. Він сумісний із WooCommerce High-Performance Order Storage (HPOS).

Плагін не підтримує підписки чи регулярні платежі, не зберігає картки, не має вбудованих полів для карток (Drop-in або Components), кнопок захоплення чи скасування в WooCommerce та базової автентифікації для вебхуків.

Замовлення та повернення коштів

Статуси замовлення

Pending payment: платіжне посилання створено, а Adyen ще не підтвердив платіж. Примітка до замовлення показує платіжне посилання, суму та середовище.

Processing, Completed or On Hold: платіж авторизовано. Статус відповідає налаштуванню Order status after payment. Примітка до замовлення показує суму, PSP reference і спосіб оплати. ID транзакції — це PSP reference Adyen.

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 повернути можна лише захоплені платежі.

Повернення, зроблені в Customer Area Adyen, надходять вебхуком і додаються до приміток замовлення. Вони не записуються автоматично як повернення 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 існує, що його адреса точно така, як показано в налаштуваннях, і що метод — JSON. Перевірте, що ключ HMAC цього вебхука вставлено в потрібне поле (Test HMAC key або Live HMAC key). За неправильного або відсутнього ключа HMAC плагін відповідає HTTP 401, і Adyen повторює доставку пізніше, тож замовлення оновиться автоматично після виправлення ключа. У журналі з'явиться Webhook rejected: invalid HMAC signature або повідомлення, що ключ HMAC не налаштовано.

Вебхук відповідає 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.

Повернення коштів не вдається: замовлення має мати PSP reference Adyen, який надходить із вебхуком AUTHORISATION. Облікові дані середовища, в якому здійснено платіж, мають бути заданими. За ручного захоплення повернути можна лише захоплені платежі.

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

Видалення

Деактивація плагіна зберігає всі дані. Щоб видалити його, деактивуйте та видаліть на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна завжди видаляються. Налаштування шлюзу та дані Adyen, збережені в замовленнях (PSP references, платіжні посилання, оброблені події), видаляються лише тоді, коли було увімкнено Delete data on uninstall. Інакше вони зберігаються для повторного встановлення. Існуючі замовлення зберігають свої примітки про оплату та ID транзакцій.

Adyen є товарним знаком відповідного власника. Цей плагін не пов'язаний із компанією Adyen і не схвалений нею.