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

Вимоги

PrestaShop: 8.0–9.x.

PHP: 8.0 або новіша версія. Модуль відмовляється встановлюватися на старіших версіях PHP.

Валюта: GoPay приймає CZK, EUR, PLN, USD, GBP, HUF, RON і BGN. За іншої валюти кошика спосіб оплати на етапі оформлення приховується.

Обліковий запис GoPay: потрібні GoID, Client ID і Client Secret вашого облікового запису мерчанта GoPay. Вони містяться в налаштуваннях інтеграції облікового запису. Тестовий обліковий запис (sandbox) має власні облікові дані. Для сповіщень в обліковому записі GoPay нічого налаштовувати не потрібно, але ваш магазин має бути доступний з інтернету.

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

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

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

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

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

4. Введіть GoID, Client ID і Client Secret для sandbox, залиште ввімкненим Test Mode, увімкніть Enable/Disable і натисніть Save.

5. Оформіть тестове замовлення. Коли все працює, введіть облікові дані робочого режиму та вимкніть Test Mode.

Під час встановлення модуль створює статус замовлення GoPay payment on hold. PrestaShop пропонує новий платіжний модуль для всіх валют, країн і груп клієнтів. Їх можна обмежити в розділі Payment > Preferences.

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox GoPay Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка показує Sandbox mode — test payments only або Production mode — real payments. Вона попереджає, коли відсутні GoID, Client ID або Client Secret поточного режиму, а також коли GoPay не приймає валюту магазину за замовчуванням. В обох випадках GoPay не пропонується на етапі оформлення. Під час збереження кешовані токени доступу GoPay очищаються, тож нові облікові дані використовуються одразу.

GoPay

Enable/Disable: Enable GoPay payment gateway вмикає або вимикає спосіб оплати. За замовчуванням: вимкнено.

Title: назва способу оплати, яка показується на етапі оформлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: GoPay. Обов'язкове поле: порожня назва не зберігається.

Description: опис способу оплати, який показується на етапі оформлення. За замовчуванням: Pay securely via GoPay - cards, wallets, bank transfers.

Облікові дані API

GoID, Client ID і Client Secret відображаються в вашому обліковому записі мерчанта GoPay (налаштування інтеграції). Тестовий обліковий запис (sandbox) має власні облікові дані. Документація API розташована на doc.gopay.com.

Test Mode: надсилає платежі на gw.sandbox.gopay.com з обліковими даними sandbox. Реальні кошти не списуються. Вимкніть, щоб приймати реальні платежі з обліковими даними робочого режиму. За замовчуванням: увімкнено.

Sandbox GoID: GoID вашого тестового облікового запису GoPay (sandbox).

Sandbox Client ID: OAuth Client ID тестового облікового запису.

Sandbox Client Secret: OAuth Client Secret тестового облікового запису.

Production GoID: ваш ідентифікатор мерчанта GoPay (GoID).

Production Client ID: OAuth Client ID, наданий GoPay.

Production Client Secret: OAuth Client Secret, наданий GoPay.

GoID містить лише цифри, наприклад 8123456789. Якщо ви введете щось інше, сторінка покаже помилку, а попереднє значення залишиться.

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

Clear saved client secrets: позначте прапорець і натисніть Save, щоб видалити обидва збережені Client Secret. Порожнє поле зберігає збережене значення.

Оплата

Payment Page Language: мова сторінки оплати GoPay. За замовчуванням: Automatic (site language, then billing country). Автоматичний режим використовує мову кошика клієнта; якщо GoPay її не підтримує, вирішує країна виставлення рахунку, а інакше використовується англійська. Також можна зафіксувати одну з 19 мов: Czech, English, Slovak, German, Polish, Hungarian, Romanian, Bulgarian, Croatian, Slovenian, Estonian, Latvian, Lithuanian, French, Italian, Spanish, Portuguese, Ukrainian або Russian.

Order Status After Payment: статус замовлення, який встановлюється після підтвердження платежу.

Платежі, що не відповідають замовленню, платежі після скасування та попередньо авторизовані платежі завжди переходять у GoPay payment on hold.

Сповіщення про платежі

Сповіщення повідомляє вашому магазину, що платіж здійснено. Notification URL показано в цьому розділі, і він надсилається в GoPay з кожним платежем, тож в обліковому записі GoPay нічого налаштовувати не потрібно. При використанні зрозумілих URL він має такий вигляд: https://your-shop/module/wcp_gopay_gateway/webhook, можливо з кодом мови, наприклад /en/. Він має бути доступний з інтернету: без захисту паролем і без брандмауера перед ним. Він працює, поки магазин перебуває в режимі обслуговування, і не блокується обмеженням за країною вашого магазину.

Сповіщення GoPay містять лише ID платежу й не мають підпису. Кожне сповіщення перевіряється запитом до API GoPay про стан платежу з обліковими даними того режиму, у якому здійснено платіж, і платіж має бути створений модулем для кошика вашого магазину. Якщо стан не вдається зчитати з GoPay, магазин відповідає помилкою, і GoPay повторює сповіщення. Без сповіщень замовлення створюється лише тоді, коли покупець повертається до магазину після оплати.

Додатково

Logging: записує події GoPay у файл logs/gopay_p_debug.log.php у папці модуля. Файл не можна відкрити через веб. Помилки та попередження записуються завжди. Облікові дані, токени, дані карток, а також e-mail і ім'я покупця ніколи не записуються. За замовчуванням: вимкнено.

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

Delete Data on Uninstall: якщо увімкнено, при видаленні модуля видаляються його налаштування, кешовані токени доступу GoPay і журнал. Замовлення, їхні платіжні дані GoPay і статус замовлення GoPay payment on hold завжди зберігаються. За замовчуванням: вимкнено.

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням GoPay) і підтверджує вибір. Модуль створює платіж GoPay на суму кошика у валюті кошика, з товарами, доставкою та подарунковим пакуванням, і надсилає покупця на сторінку оплати GoPay. Там GoPay пропонує способи оплати, увімкнені у вашому обліковому записі GoPay, наприклад платіжні картки, банківські перекази та електронні гаманці. Ім'я для виставлення рахунку, e-mail, телефон і адреса покупця передаються в GoPay; порожні поля не надсилаються. У GoPay платіж відображається як Order PS- і номер кошика. На цьому етапі замовлення ще не існує.

Після оплати покупець повертається до вашого магазину. Замовлення позначається як оплачене лише після підтвердження GoPay: сповіщенням або запитом до API GoPay, коли покупець повертається. Сповіщення та повернення, що надходять одночасно, обробляються по черзі, тож створюється лише одне замовлення. Потім покупець бачить стандартну сторінку підтвердження замовлення. Якщо замовлення перейшло в GoPay payment on hold, на сторінку додається повідомлення Your payment is being reviewed. We will contact you if anything else is needed.

Якщо GoPay ще не підтвердив платіж, коли покупець повертається (наприклад, банківський переказ у дорозі або GoPay недоступний), сторінка Payment confirmation показує GoPay has not confirmed your payment yet. Your order will be created automatically as soon as the payment is confirmed — please do not pay again. з кнопкою Check again.

Якщо платіж не було завершено, його скасовано або термін минув, покупець повертається до оформлення з повідомленням The GoPay payment was not completed. You can try again or choose another payment method. або The GoPay payment was cancelled or has expired. You can try again or choose another payment method. Кошик зберігається, а нова спроба створює новий платіж GoPay. Кошик, для якого вже є замовлення, ніколи не списується повторно.

Якщо GoPay не може розпочати платіж, покупець залишається на етапі оформлення з коротким повідомленням, наприклад GoPay could not accept the payment details. Please check your billing details (e-mail, phone, address) or choose another payment method. або GoPay is temporarily unavailable. Please try again in a moment or choose another payment method. Технічна причина записується в журнал.

Спосіб оплати покупець обирає на сторінці GoPay; у PrestaShop його обрати не можна. Модуль не підтримує підписки чи регулярні платежі, збережені картки, вбудовану платіжну форму, а також захоплення чи анулювання попередніх авторизацій із PrestaShop.

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

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

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

Payment accepted or Delivered: платіж підтверджено. Статус відповідає Order Status After Payment. Платіж записується з ID платежу GoPay як ID транзакції, а примітка показує ID платежу та спосіб оплати.

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

Refunded: платіж GoPay за замовленням повністю повернуто — через модуль або в обліковому записі GoPay.

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

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

На сторінці замовлення показано блок GoPay payment з ID платежу GoPay, станом і способом оплати в GoPay, сумою платежу, сумами оплаченою та поверненою, значком Sandbox для тестових платежів, причиною ручної перевірки, історією повернень і GoPay notes замовлення.

Повернення

У блоці GoPay payment введіть суму (підставляється сума, яку ще не повернуто), за бажанням причину, і натисніть Refund via GoPay. Підтвердіть запитання Refund this amount through GoPay? This cannot be undone. Підтримуються повні та часткові повернення. Потрібне право редагувати замовлення; доступ до сторінок Modules не потрібен. GoPay приймає часткові повернення лише протягом 24 годин після платежу. Повернення виконуються на суму та у валюті, які списав GoPay, тож після розбіжності суми чи валюти можна повернути не більше того, що покупець фактично сплатив. Повернення надсилається в тому режимі, у якому здійснено платіж (sandbox або робочому), тому облікові дані цього режиму мають бути заповнені. Якщо GoPay відхиляє повернення, блок показує повідомлення GoPay, і повернення не записується. Успішне повернення додається до історії повернень і приміток; повернення, яке GoPay прийняв до пізнішої обробки, позначається як прийняте. Повне повернення переводить замовлення в статус Refunded. Часткове повернення статус не змінює.

Модуль не створює кредитні нотатки (credit slips). Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають гроші через GoPay.

Повернення, виконані в обліковому записі GoPay, надходять через сповіщення. Повне повернення переводить замовлення в статус Refunded; часткове додає примітку. У історію повернень блоку вони не додаються.

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

Модуль працює з ліцензійним ключем VibeFox із vibefox.net. Блок ліцензії License — VibeFox GoPay Gateway — це перший блок на сторінці Modules > Module Manager > VibeFox GoPay Gateway > Configure, над налаштуваннями. Введіть ключ у поле License key і натисніть Activate. Після цього блок показує ключ приховано, статус (наприклад, дату, до якої ліцензія активна, і ваш домен) та кнопки Check now, щоб перевірити статус ще раз, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього магазину. Нижче розміщені рядок Product: presta-payment-gopay і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише співробітники з правом Configure для модуля. Тексти блоку відповідають мові back office (включено англійську та російську).

Якщо ключ не прийнято, блок повідомляє причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on із датою. Після зміни адреси магазину або після звільнення слота домену у вашому обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, модуль продовжує працювати за останнім відомим статусом.

Один ключ працює на одному домені: на домені основного магазину, також у мультимагазинній конфігурації. Видалення ключа з магазину не звільняє слот домену. Звільніть слот у своєму обліковому записі vibefox.net.

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

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

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

GoPay не з'являється на етапі оформлення: перевірте, що ліцензія активна, Enable/Disable увімкнено, для поточного режиму заповнені GoID, Client ID і Client Secret, а валюта кошика — одна з CZK, EUR, PLN, USD, GBP, HUF, RON або BGN. Сторінка налаштувань показує попередження, коли облікові дані відсутні. У Payment > Preferences перевірте, що модуль дозволений для валюти кошика, країни покупця та групи покупця.

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

Notification answers Order not found: платіж створено не цим магазином, або його кошик було видалено.

Notification answers Payment state could not be verified: API GoPay недоступний, або облікові дані цього режиму відсутні чи неправильні. GoPay повторює сповіщення.

Notification answers Busy, retry later: кошик у той самий момент оброблявся іншим запитом, або замовлення не вдалося створити (наприклад, модуль вимкнено). GoPay повторює сповіщення. Увімкніть Logging, щоб побачити причину.

Покупець бачить помилку, коли обирає GoPay: увімкніть Logging і перегляньте поле Log. Неправильні облікові дані або облікові дані іншого режиму — звичайна причина. Повідомлення про платіжні дані означає, що GoPay не прийняв e-mail, телефон або адресу.

Тестові платежі не підтверджують реальне замовлення: sandbox і робочий режим розділені. Кожен платіж перевіряється в тому режимі, у якому був створений. Переведіть Test Mode у потрібний режим і використовуйте облікові дані цього режиму.

Замовлення в статусі GoPay payment on hold після оплати: прочитайте примітки в блоці GoPay payment. Оплачена сума або валюта відрізнялися від кошика, платіж надійшов після скасування замовлення, або платіж лише попередньо авторизовано.

Повернення не виконується: прочитайте повідомлення GoPay у блоці. Часткове повернення можливе лише протягом 24 годин після платежу. Повідомлення про режим означає, що платіж здійснено в тестовому або робочому режимі, а облікові дані цього режиму не заповнені.

Для розробників: хук actionGopayPaymentPayload змінює запит на оплату до його надсилання в GoPay.

Видалення

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

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