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-токен вашого тестового облікового запису HyperPay.
Test Entity ID: Entity ID тестового платіжного каналу.
Test Webhook Key: 64-символьний шістнадцятковий ключ для розшифрування сповіщень вебхуків тестової системи.
Live Access Token: bearer-токен вашого робочого облікового запису HyperPay.
Live Entity ID: Entity ID робочого платіжного каналу.
Live Webhook Key: 64-символьний шістнадцятковий ключ для розшифрування сповіщень вебхуків робочої системи.
Webhook
Вебхук повідомляє ваш магазин про платежі, навіть якщо покупець закрив браузер, не повернувшись до магазину. У панелі HyperPay (Administration > Webhooks) додайте вебхук для платежів з 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.