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

Вимоги

PrestaShop: 8.0–9.x.

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

HTTPS: ваш магазин має бути доступний з інтернету через HTTPS, щоб Comgate міг доставити фонове сповіщення.

Валюта: CZK, EUR, PLN, HUF, USD, GBP, RON, HRK, NOK або SEK. Для інших валют і для сум нижче мінімуму Comgate спосіб оплати приховується. Платежі в HUF округлюються до цілих форинтів, як того вимагає Comgate.

Обліковий запис Comgate: потрібні Merchant ID і секрет (пароль для фонової комунікації) підключення вашого магазину в клієнтському порталі Comgate, а також URL сповіщення, вказаний там (див. «Налаштування»). Comgate використовує однакові Merchant ID і секрет для тестових і бойових платежів.

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

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

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

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

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

4. Введіть Merchant ID і Secret з клієнтського порталу Comgate та вкажіть там URL сповіщення (див. «Налаштування»).

5. Увімкніть Enable / Disable і натисніть Save. Залиште Test Mode увімкненим для пробного платежу, а потім вимкніть його.

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

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

Усі налаштування розміщені на сторінці модуля: Modules > Module Manager > VibeFox Comgate Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, якщо Comgate увімкнено, але не заповнено Merchant ID або секрет (тоді спосіб оплати приховано на оформленні, доки обидва поля не заповнені), а також якщо основна валюта магазину не підтримується Comgate. Поки увімкнено тестовий режим, вона показує Test mode is on: payments are created as Comgate test payments and no money is charged. Turn it off before going live.

Comgate

Enable / Disable: Enable Comgate Payment Gateway вмикає або вимикає спосіб оплати. Default: off.

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

Description: текст під способом оплати на оформленні. Default: Pay securely via Comgate — cards, bank transfers, wallets and more. У тестовому режимі до нього додається TEST MODE: no real money is charged., або ця фраза показується окремо, якщо опис порожній.

Підключення до Comgate

Візьміть ідентифікатор магазину (Merchant ID) і пароль (секрет) у клієнтському порталі Comgate, розділ Integration > shop connection settings. Там само вкажіть URL for passing the payment result (фонове сповіщення), що дорівнює URL з поля Notification URL у цьому розділі. З дружніми URL він має вигляд https://your-shop/module/wcp_comgate_gateway/webhook, можливо з кодом мови, наприклад /en/. Копіюйте URL точно так, як він показаний у налаштуваннях. Comgate викликає його після кожного платежу; модуль потім повторно перевіряє платіж через API статусу Comgate, перш ніж щось змінити. Адреси повернення для покупця передаються з кожним платежем. Якщо портал також вимагає адреси повернення (оплачено, скасовано, очікування), використовуйте другий URL із цього розділу, який закінчується на return?id=${id}&refId=${refId}.

Merchant ID: ідентифікатор магазину (merchant) в Comgate.

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

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

Test Mode: створює тестові платежі (кошти не списуються). Comgate використовує однакові Merchant ID і секрет для тестових і бойових платежів; тестові платежі позначаються test=true. Повернення завжди надсилаються в режимі початкового платежу. Default: on.

Сторінка оплати

Payment Methods: які способи оплати Comgate може обрати покупець. Показуються лише способи, увімкнені для вашого магазину в Comgate.

Language: мова платіжної сторінки Comgate. Automatic (shop language, English as fallback) (типово) або одна з 26 мов.

Замовлення

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

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

Додатково

Debug Log: записує запити до API та сповіщення у файл logs/comgate_p_debug.log.php у папці модуля. Відкрити файл через веб не можна. Секрет і персональні дані ніколи не записуються в журнал. Помилки записуються завжди. Default: off.

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

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Comgate) і підтверджує замовлення. Модуль створює платіж у Comgate на суму кошика у валюті кошика та перенаправляє покупця на платіжну сторінку Comgate. Електронна адреса й ім'я покупця передаються в Comgate, а платіж позначається як Cart з номером кошика. Потрібна дійсна адреса електронної пошти. На сторінці Comgate покупець платить одним із дозволених вами способів. На цьому етапі замовлення ще не існує.

Після оплати покупець повертається до вашого магазину. Замовлення позначається як оплачене лише після підтвердження Comgate: модуль зчитує платіж через API статусу Comgate, як тоді, коли надходить фонове сповіщення, так і тоді, коли покупець повертається. Потім створюється замовлення, і покупець бачить стандартну сторінку підтвердження замовлення. Якщо замовлення було переведено в очікування, сторінка додає повідомлення Your payment is being reviewed. We will contact you if anything else is needed. Якщо попередньо авторизоване замовлення пізніше було скасовано, сторінка показує Your Comgate payment was not completed. Please contact us about this order.

Якщо платіж ще не підтверджено, коли покупець повертається, наприклад банківський переказ у дорозі, з'являється сторінка Payment confirmation з повідомленням Comgate 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 і Back to checkout.

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

Якщо Comgate не може розпочати платіж, покупець лишається на оформленні з коротким повідомленням, наприклад The Comgate payment could not be started. Please try again or choose another payment method., що Comgate не може прийняти цю суму чи валюту, або що обраний спосіб оплати Comgate недоступний. Технічна причина записується в журнал.

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

Модуль приймає разові платежі лише на сторінці Comgate. Він не підтримує регулярні платежі, підписки чи збережені картки, не надає вбудованого checkout Comgate, не виводить на вашому сайті кнопки Apple Pay або Google Pay (вони доступні на сторінці Comgate) і не підтверджує та не скасовує попередні авторизації з PrestaShop. Без сповіщення статус платежу автоматично не опитується; він перевіряється лише тоді, коли покупець повертається.

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

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

Замовлення ще немає: покупця надіслано до Comgate, і він ще не оплатив, або Comgate повідомляє про платіж як про очікуваний. Існує лише кошик.

Payment accepted or Delivered: Comgate повідомив про платіж як про PAID з тією самою сумою і валютою. Статус відповідає Order Status After Payment. Платіж записується з ідентифікатором транзакції Comgate. Тестові платежі отримують примітку Comgate test payment — no money was charged.

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

Canceled: авторизований платіж було скасовано або він прострочений у Comgate. Якщо Comgate підтверджує платіж після цього, замовлення знову відкривається як оплачене з приміткою перевірити наявність товару перед відправкою.

Refunded: платіж повністю повернено через модуль.

Якщо Comgate повідомляє ще про один платіж PAID для вже оплаченого замовлення, замовлення не змінюється. Примітка просить перевірити це в порталі Comgate та повернути дубль. Повторно надіслане підтвердження ніколи не відкриває знову повернене замовлення.

Блок оплати Comgate

На сторінці замовлення показано блок Comgate payment з ідентифікатором транзакції, статусом Comgate, сумою платежу, сумою замовлення та сумою повернення, позначку Test mode для тестових платежів, причину перевірки, історію повернень і Comgate notes замовлення.

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

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

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

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

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

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

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

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

Comgate не з'являється на оформленні: перевірте, що ліцензія активна, Enable / Disable увімкнено, заповнені Merchant ID і Secret, валюта кошика підтримується, а сума замовлення не нижча за мінімум Comgate (наприклад 1 CZK, 0,10 EUR або 100 HUF). У Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи покупця.

Платіж пройшов, але замовлення не створено: Comgate не доставив фонове сповіщення. Перевірте URL for passing the payment result у порталі Comgate (саме Notification URL з налаштувань), доступність вашого магазину через HTTPS з інтернету та журнал (увімкніть Debug Log). Comgate повторює недоставлені сповіщення; модуль відповідає помилкою щоразу, коли не обробив сповіщення, тож воно буде надіслано знову. Замовлення також створюється, коли покупець повертається до магазину.

Сповіщення відповідає Invalid merchant or secret: Merchant ID або секрет у налаштуваннях не відповідають підключенню магазину в порталі Comgate.

Сповіщення відповідає Gateway not configured: Merchant ID або секрет у налаштуваннях порожні. Comgate повторить спробу, коли їх буде заповнено.

Сповіщення відповідає Unknown transaction, Order not found або Reference mismatch: сповіщення стосується платежу, який цей магазин не створював для цього кошика. Нічого не змінюється.

Сповіщення відповідає Status verification failed, Status verification rejected або Busy, retry later: API статусу Comgate був недоступний, відхилив запит, або кошик у цей момент оброблявся іншим запитом. Busy також є відповіддю, коли замовлення не вдалося створити; причина вказана в журналі. Comgate повторить сповіщення.

URL сповіщення в браузері показує code=1&message=POST%20required: це нормально. URL приймає лише запити від Comgate.

Покупець бачить We could not verify the Comgate payment: посилання повернення не збіглося з кошиком. Якщо кошти списано, сповіщення все одно створить замовлення. Перевірте платіж у порталі Comgate, перш ніж покупець заплатить знову.

Покупець бачить The order total is below the minimum amount accepted by Comgate або A valid billing e-mail address is required for Comgate payments: цей кошик не можна оплатити через Comgate у поточному вигляді.

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

Повернення не виконується: прочитайте повідомлення в блоці. Comgate rejected the refund: the amount exceeds the refundable amount. означає, що сума більша за залишок до повернення; платіж у статусі, відмінному від PAID, повернути не можна. Comgate could not be reached. The refund was not made — please try again later. означає проблему зі з'єднанням.

Видалення

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

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