VibeFox HyperPay for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0–9.x.

PHP: 8.0 або новіша версія з розширенням OpenSSL (воно розшифровує вебхуки). Без нього модуль не встановлюється.

Обліковий запис HyperPay: HyperPay видає Access Token і Entity ID під час налаштування вашого облікового запису мерчанта. Тестові та робочі дані різні. Також потрібен платіжний вебхук у панелі HyperPay та його ключ розшифрування (webhook key), який показано в розділі Administration > Webhooks (див. Налаштування).

Дані картки: картка вводиться лише у віджеті HyperPay, тож дані картки ніколи не потрапляють на ваш сервер (PCI DSS SAQ A).

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

Встановлення

1. У back office відкрийте Modules > Module Manager і натисніть Upload a module. Оберіть ZIP-файл модуля.

2. Коли завантаження завершиться, натисніть Configure або пізніше знайдіть VibeFox HyperPay Payment Gateway у списку модулів і натисніть Configure.

3. Введіть ліцензійний ключ VibeFox у поле License key блоку ліцензії вгорі сторінки Configure і натисніть Activate (див. Ліцензійний ключ).

4. Введіть тестові Access Token, Entity ID і ключ вебхука, видані HyperPay, і залиште увімкненим Test Mode.

5. У панелі HyperPay (Administration > Webhooks) додайте платіжний вебхук з URL, що показаний у розділі Webhook, і скопіюйте його ключ розшифрування в поле ключа вебхука того самого режиму.

6. Увімкніть Enable/Disable, натисніть Save і проведіть тестову оплату тестовою карткою HyperPay. Потім введіть робочі дані та вимкніть Test Mode.

Під час встановлення модуль створює три статуси замовлення: Awaiting HyperPay payment, HyperPay payment authorized і HyperPay payment on hold. PrestaShop прив'язує новий платіжний модуль до валют, країн і груп клієнтів, які активні на цей момент. Країни, які ви активуєте пізніше, потрібно дозволити в Payment > Preferences.

Налаштування

Усі налаштування розміщено на сторінці модуля: Modules > Module Manager > VibeFox HyperPay Payment Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка показує Test mode is on: payments go to the HyperPay test system and no real money is charged., поки ввімкнено тестовий режим. Вона попереджає, якщо немає Access Token або Entity ID поточного режиму (тоді спосіб оплати не показується в оформленні), і якщо в поточному режимі немає дійсного ключа вебхука (тоді платежі підтверджуються лише коли покупець повертається до магазину). Під час збереження пробіли видаляються з облікових даних, а сторінка попереджає, якщо ключ вебхука не є 64-символьним шістнадцятковим ключем.

HyperPay

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: використовує тестову систему HyperPay (eu-test.oppwa.com) і тестові облікові дані. Реальні кошти не списуються. Вимкніть режим, щоб приймати реальні платежі з робочими обліковими даними (eu-prod.oppwa.com). За замовчуванням: увімкнено. Поки режим увімкнено, покупці бачать Test mode: no real payment will be made. під способом оплати.

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-символьний шістнадцятковий ключ для розшифрування сповіщень вебхука робочої системи.

Збережені access tokens і ключі вебхуків більше ніколи не показуються. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Очистити збережені секрети: позначте токен або ключ і натисніть Save, щоб видалити його. Порожнє поле зберігає збережене значення.

Webhook

Вебхук повідомляє ваш магазин про платежі навіть тоді, коли покупець закриває браузер до повернення в магазин. У панелі HyperPay (Administration > Webhooks) додайте вебхук для платежів з URL, який показано в полі Webhook URL у цьому розділі. З дружніми URL він має вигляд https://your-shop/module/wcp_hyperpay_payment_gateway/webhook, можливо, з кодом мови, наприклад /en/. Копіюйте URL точно так, як його показують налаштування. Потім скопіюйте ключ розшифрування вебхука в поле Test Webhook Key або Live Webhook Key того самого режиму.

Вебхуки HyperPay зашифровані (AES-256-GCM). Вебхук, який неможливо розшифрувати вашими ключами, відхиляється. Обробляються лише сповіщення про платежі, і платіж має належати до платіжної сесії одного з ваших кошиків, створеної в тому самому режимі, що й ключ, яким його розшифровано. Тестові сповіщення HyperPay підтверджуються. Вебхук також повідомляє про захоплення, реверси, повернення коштів і чарджбеки, зроблені в панелі HyperPay (див. Замовлення та повернення коштів). Без вебхука платіж підтверджується лише тоді, коли покупець повертається до магазину після оплати.

Payment

Transaction Type: як списуються кошти з картки.

Payment Brands: бренди, які показуються у платіжному віджеті: VISA, Mastercard, mada, American Express, STC Pay, Apple Pay. За замовчуванням: VISA і Mastercard. Якщо жоден бренд не позначено, сторінка попереджає, а віджет показує VISA і Mastercard. Обирайте лише ті бренди, які HyperPay увімкнув для вашого Entity ID; mada, STC Pay і Apple Pay часто використовують власну entity, яку цей модуль не підтримує.

Advanced

Enable Logging: записує запити та відповіді API у logs/hyperpay_p_debug.log.php у папці модуля. Файл не можна відкрити через веб. Помилки та попередження завжди записуються. Журнали не містять даних карток, ключів або даних покупців. За замовчуванням: вимкнено.

Log: показує розмір і останні записи журналу. Натисніть Clear log, щоб його очистити.

Delete Data on Uninstall: якщо увімкнено, видалення модуля вилучає налаштування, таблицю спроб платежів HyperPay і файли журналів. Замовлення та статуси замовлень модуля зберігаються. За замовчуванням: вимкнено.

Оформлення замовлення

На кроці оплати покупець обирає спосіб оплати (за замовчуванням Credit/Debit Card (HyperPay)) і підтверджує замовлення. Модуль готує платіжну сесію HyperPay на суму кошика у валюті кошика та відкриває сторінку HyperPay payment вашого магазину з віджетом HyperPay і написом Please complete your payment below:. Віджет використовує мову покупця, якщо HyperPay її підтримує. У тестовому режимі сторінка показує Test mode: use a HyperPay test card, no real payment will be made. Покупець вводить дані картки у віджеті або переходить за посиланням Choose another payment method, щоб повернутися до оформлення. На цьому етапі замовлення ще немає. Перезавантаження сторінки повторно використовує ту саму платіжну сесію до 25 хвилин, поки кошик не змінюється.

Після оплати покупець повертається до вашого магазину. Модуль перевіряє, що платіж належить до однієї з платіжних сесій цього кошика, і запитує результат у HyperPay серверним запитом, у тому режимі, в якому створено сесію. Замовлення позначається оплаченим лише тоді, коли HyperPay підтверджує платіж: цим запитом або вебхуком. Сума та валюта мають збігатися з кошиком. Якщо повернення та вебхук надходять одночасно, їх обробляють по черзі, тож замовлення ніколи не створюється двічі. Коли платіж підтверджено, замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення.

Якщо платіж не пройшов, покупець повертається в оформлення з повідомленням: Payment failed: і причиною від HyperPay, Payment was not completed. Please try again. або We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again. Кошик зберігається, і покупець може оплатити знову; кожна нова спроба отримує нову платіжну сесію HyperPay. Якщо платіжну форму не вдалося підготувати, покупець залишається в оформленні з коротким повідомленням, наприклад, що платіжний провайдер не прийняв деякі платіжні дані, або що платіжна форма недоступна через помилку конфігурації оплати. Технічна причина записується в журнал.

Суми передаються з двома десятковими знаками, як того вимагає API HyperPay. Для валют із трьома десятковими знаками (KWD, BHD, JOD, OMR) сума кошика округлюється до двох знаків.

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

Модуль не підтримує повернення коштів і анулювання з PrestaShop, збережені картки або токенізацію, підписки, перевірку домену для Apple Pay, окремі Entity ID для кожного бренду, а також Tabby, Tamara та інші методи «купуйте зараз, платіть пізніше».

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

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

No order yet: покупець був перенаправлений на сторінку оплати і не сплатив, платіж було відхилено або HyperPay ще не підтвердив платіж. Існує лише кошик.

Payment accepted: підтверджено платіж зі списанням або захоплено попередню авторизацію. Платіж записується з ID платежу HyperPay як ID транзакції, а приватна примітка показує код результату HyperPay, опис і ID платежу. Якщо HyperPay позначив платіж для ручної перевірки, примітка про це повідомляє; перевірте його в панелі HyperPay перед відправленням.

HyperPay payment authorized: суму зарезервовано попередньою авторизацією. Захопіть її в блоці HyperPay замовлення або в панелі HyperPay; вебхук захоплення потім переводить замовлення в статус Payment accepted.

Awaiting HyperPay payment: HyperPay повідомив, що платіж очікує. Замовлення переходить у статус Payment accepted, коли HyperPay підтверджує платіж.

HyperPay payment on hold: HyperPay повідомив суму або валюту, що відрізняються від кошика чи замовлення (наприклад, кошик було змінено після відкриття сторінки оплати), або платіж надійшов після скасування замовлення. Примітка пояснює причину. Перевірте платіж у панелі HyperPay, потім виконайте замовлення або поверніть кошти за платежем.

Canceled: попередню авторизацію було реверсовано в панелі HyperPay, і вебхук реверсу скасовує авторизоване замовлення.

Відхилений результат ніколи не змінює наявне замовлення. Якщо для вже оплаченого замовлення надходить ще один успішний платіж, замовлення не змінюється. Примітка просить повернути дублікат у панелі HyperPay. Успішний платіж за замовлення, для якого вже повернено кошти, лише додає примітку.

Блок платежу HyperPay

Сторінка замовлення показує блок HyperPay payment з ID платежу (і ID захоплення після захоплення), типом транзакції, ID платіжної сесії, ID транзакції мерчанта, сумою, надісланою в HyperPay, результатом і позначкою Test mode для тестових платежів. Примітки модуля містяться в приватних повідомленнях замовлення.

Захоплення

Для замовлення в статусі HyperPay payment authorized блок показує Capture payment із сумою. Натисніть і підтвердьте Capture the pre-authorized amount through HyperPay?. Захоплюється поточна сума замовлення в тому режимі, в якому було зроблено попередню авторизацію, тому Access Token і Entity ID цього режиму мають бути заповнені. Потрібне право редагувати замовлення; доступ до сторінок модуля не потрібен. Після успішного захоплення замовлення переходить у статус Payment accepted, а ID захоплення додається до платежу та приміток. Якщо HyperPay відмовляє в захопленні, показуються код результату та опис, вони додаються до приміток, а замовлення залишається авторизованим. Подвійний клік не захоплює кошти двічі. Реверс (void) попередньої авторизації виконується в панелі HyperPay.

Повернення коштів

Повернення коштів із PrestaShop не підтримуються, а стандартні кнопки повернення PrestaShop не повертають гроші через HyperPay. Поверніть платіж у панелі HyperPay і зафіксуйте його в PrestaShop частковим поверненням або кредит-нотою, якщо потрібно. Повернення коштів і чарджбеки, зроблені в HyperPay, вебхук додає до замовлення як примітку; статус замовлення не змінюється.

Ліцензійний ключ

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

Без активного ключа HyperPay не показується покупцям в оформленні. Якщо платіж все одно розпочато, покупець бачить This payment method is not available. Please choose another one. Магазин PrestaShop не знає, що ви увійшли в бек-офіс, тож спосіб оплати приховано і для вас: модуль можна налаштувати до купівлі ключа, але не можна протестувати в оформленні. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Наявні замовлення не змінюються: платежі, які вже розпочато, і далі підтверджуються, а захоплення та повернення коштів працюють.

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

Усунення несправностей

HyperPay не з'являється в оформленні: перевірте, що ліцензія активна, Enable/Disable увімкнено, а в поточному режимі є Access Token і Entity ID: тестові — у тестовому режимі, робочі — у робочому. Сторінка налаштувань показує попередження, якщо їх немає. У Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи покупця.

Платіж пройшов, але замовлення не створено: вебхук не працює, а покупець не повернувся до магазину. У панелі HyperPay перевірте, що платіжний вебхук існує для режиму, який ви використовуєте, що його URL точно збігається з показаним у Webhook URL, і що його ключ розшифрування знаходиться в полі ключа вебхука того самого режиму. Увімкніть Enable Logging і перегляньте поле Log на сторінці модуля.

Вебхук відповідає Decryption failed: ключ вебхука належить іншому вебхуку або іншому режиму. Скопіюйте ключ знову з панелі HyperPay.

Вебхук відповідає Webhook key not configured: не задано дійсний ключ вебхука. Вставте 64-символьний ключ у налаштування. HyperPay повторить вебхук.

Вебхук відповідає Busy, retry later: замовлення в цей момент оброблявся іншим запитом, або замовлення не вдалося створити (наприклад, модуль вимкнено). HyperPay повторить вебхук. Причину записано в журнал.

Журнал показує Webhook ignored: платіж не належить до кошика цього магазину, або його було зроблено в іншому режимі. Тестові та робочі платежі розділені.

URL вебхука в браузері показує Method not allowed: це нормально. URL приймає лише POST-запити від HyperPay.

Платіжна форма не завантажується: перегляньте журнал. Помилка конфігурації зазвичай означає неправильні Access Token або Entity ID для поточного режиму. Повідомлення про платіжні дані означає, що HyperPay не прийняв деякі дані покупця. Переконайтеся, що вибрані Payment Brands увімкнені для вашого Entity ID.

Замовлення в статусі HyperPay payment on hold: прочитайте примітки замовлення (див. Статуси замовлення), перевірте платіж у панелі HyperPay, потім виконайте замовлення або поверніть кошти за платежем.

Захоплення не вдається: прочитайте код результату та опис у блоці й примітках. Захоплення надсилається в режимі попередньої авторизації, тому облікові дані цього режиму мають бути заповнені; інакше блок повідомить, що Access Token / Entity ID цього режиму порожні.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox HyperPay Payment Gateway і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Delete Data on Uninstall увімкнено, налаштування, таблицю спроб платежів HyperPay і файли журналів буде видалено. Якщо вимкнено, усе зберігається для повторного встановлення пізніше. Статуси замовлення Awaiting HyperPay payment, HyperPay payment authorized і HyperPay payment on hold завжди зберігаються. Наявні замовлення зберігають свої примітки про платежі та ID транзакцій.

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