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

Вимоги

PrestaShop: від 8.0 до 9.x.

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

HTTPS: ваш магазин має використовувати HTTPS, оскільки форма картки розміщена на сторінці оформлення замовлення.

Обліковий запис OpenPay: обліковий запис OpenPay з Мексики, Колумбії або Перу. Вам потрібні його Merchant ID, закритий ключ (sk_...) і відкритий ключ (pk_...). Панелі пісочниці та робочого режиму мають різні Merchant ID і ключі, і модуль зберігає їх окремо.

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

Картка вводиться на сторінці оформлення замовлення, але зчитується і токенізується в браузері бібліотекою openpay.js. Поля картки не мають імені і ніколи не надсилаються на ваш сервер. Оскільки форма картки розміщена на вашій сторінці, ваша зона відповідальності PCI DSS — SAQ A-EP; уточніть це у свого еквайєра.

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

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

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

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

4. Оберіть Account country і введіть ключі пісочниці та робочого режиму (див. «Налаштування»).

5. Рекомендовано: додайте URL вебхука в панелі OpenPay (див. «Налаштування»).

6. Увімкніть Enable / Disable і натисніть Save. Перевірте оплату тестовими картками пісочниці OpenPay, а потім вимкніть Sandbox mode, щоб приймати реальні платежі.

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

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

Усі параметри розміщені на сторінці модуля: Modules > Module Manager > VibeFox OpenPay Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, коли ключі поточного режиму неповні (спосіб оплати тоді приховується на оформленні замовлення), коли валюта за замовчуванням вашого магазину не приймається обраною країною облікового запису, і показує Sandbox mode is enabled — no real charges are made., поки ввімкнено режим пісочниці.

Під час збереження ключі перевіряються. Merchant ID може містити лише літери та цифри, закритий ключ має починатися з sk_, а відкритий — з pk_. Некоректне значення не зберігається: лишається попереднє значення і з'являється помилка, наприклад Sandbox: The private key must start with sk_. Якщо спосіб оплати увімкнено, але ключі поточного режиму неповні, ви також побачите повідомлення, що шлюз залишається прихованим на оформленні замовлення. Порожнє поле Title не приймається, з'являється Enter a title for the payment method.

OpenPay

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

Title: назва способу оплати, яку бачать покупці на оформленні замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: Credit or debit card (OpenPay). Обов'язково.

Description: текст над формою картки на оформленні замовлення. За замовчуванням: Pay securely with your credit or debit card. Your bank may ask you to confirm the payment (3D Secure).

Обліковий запис OpenPay

Merchant ID, закритий ключ (sk_) і відкритий ключ (pk_) містяться в панелі OpenPay у розділі Settings (Configuración). Розділ містить посилання на панелі пісочниці та робочого режиму для Мексики, Колумбії та Перу.

Account country: країна вашого облікового запису OpenPay. Вона визначає API OpenPay, бібліотеку openpay.js цієї країни та прийнятні валюти. За замовчуванням: Mexico.

Sandbox mode: використовує пісочницю OpenPay (тестові ключі, без реальних списань) і перемикає і ключі, і API на пісочницю. Поки режим увімкнено, на оформленні замовлення показується позначка SANDBOX MODE. За замовчуванням: увімкнено. Вимкніть його, щоб приймати реальні платежі.

Sandbox Merchant ID: Merchant ID з панелі пісочниці, Settings (Configuración), API-ключі.

Sandbox Private Key: закритий ключ пісочниці. Починається з sk_. Використовується лише на сервері; нікому його не передавайте.

Sandbox Public Key: відкритий ключ пісочниці. Починається з pk_. openpay.js використовує його в браузері для токенізації картки.

Live Merchant ID: Merchant ID з панелі робочого режиму, Settings (Configuración), API-ключі.

Live Private Key: закритий ключ робочого режиму (sk_...).

Live Public Key: відкритий ключ робочого режиму (pk_...).

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

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

Webhook

Вебхук не є обов'язковим, але рекомендований. Він підтверджує платежі, коли покупець не повертається зі сторінки 3D Secure, наприклад після закриття браузера. У панелі OpenPay перейдіть до Settings > Webhooks і додайте URL, який показано в полі Webhook URL у цьому розділі. З понятними URL він має вигляд https://your-shop/module/wcp_openpay_gateway/webhook, можливо з кодом мови, наприклад /en/. Скопіюйте його точно так, як показано в налаштуваннях. Додайте вебхук у панель кожного режиму, який використовуєте (пісочниці та робочого).

Коли ви додаєте вебхук, OpenPay надсилає на цю URL код перевірки. Код з'являється в цьому розділі з датою надходження, щоб ви могли підтвердити вебхук у панелі OpenPay.

Оберіть ці події (вони також перелічені в цьому розділі):

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

Додатково

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

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

Delete data on uninstall: якщо увімкнено, під час видалення модуля видаляються налаштування шлюзу, збережений код перевірки вебхука та журнали. Записи списань OpenPay за замовленнями є історією платежів і завжди зберігаються, тому замовлення можна повернути й після повторного встановлення. За замовчуванням: вимкнено.

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

На кроці оплати покупець обирає спосіб оплати (за замовчуванням Credit or debit card (OpenPay)) і заповнює Cardholder name, Card number, Expiry (MM/YY) і Card code (CVV). У режимі пісочниці форма показує SANDBOX MODE — Test environment. No real charges will be made. Коли покупець підтверджує, openpay.js перетворює картку на одноразовий токен у браузері, а антифрод-бібліотека додає ID сесії пристрою. Вашому магазину надсилаються лише ці два значення та номер кошика. Якщо форма заповнена не повністю, під нею з'являється Please fill in all card fields.

Далі модуль створює списання з 3D Secure на суму кошика у валюті кошика і надсилає покупця на сторінку 3D Secure його банку, яку обслуговує OpenPay. Кожна спроба отримує власне посилання на замовлення в OpenPay. Опис списання — Cart #, номер кошика і назва вашого магазину. Ім'я, e-mail і телефон покупця передаються в OpenPay; обліковий запис покупця в OpenPay не створюється. На цьому етапі замовлення ще немає.

Коли покупець повертається, модуль зчитує списання з API OpenPay. Замовлення позначається як оплачене лише після підтвердження OpenPay: списання має належати цьому кошику, бути завершеним і точно збігатися із сумою та валютою кошика. Тоді замовлення створюється, і покупець бачить сторінку підтвердження замовлення з Your card payment has been received. Якщо OpenPay повідомляє, що списання виконується, замовлення створюється в статусі Awaiting OpenPay payment, а сторінка показує We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. Якщо результат ще невідомий, сторінка Payment confirmation показує той самий текст з кнопкою Check again і кнопкою Back to checkout; вебхук створює замовлення, щойно надійде. Якщо списання, що виконувалося, пізніше не вдалося, сторінка підтвердження замовлення показує Your OpenPay card payment was not completed. Please contact us about this order.

Якщо картку відхилено або 3D Secure не пройдено, покупець повертається на оформлення замовлення з повідомленням The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. і може оплатити знову. Кошик зберігається. Перед новою спробою модуль перевіряє попереднє списання кошика: якщо його фактично оплачено, замовлення створюється за ним без другого списання; якщо воно ще виконується, замовлення створюється в статусі Awaiting OpenPay payment; якщо його стан неможливо перевірити, нове списання не робиться, і покупець бачить We could not confirm the status of your previous payment attempt. Please try again in a few minutes. Кошик, для якого вже є замовлення, ніколи не списується повторно.

Відхилені картки отримують зрозуміле повідомлення, наприклад The card has insufficient funds. Please use another card., The card has expired. Please use another card. або The security code (CVV) is not valid. Please check it and try again. Технічні помилки OpenPay покупцям ніколи не показуються; вони потрапляють у журнал.

Якщо купон у кошику перестає бути дійсним між оплатою і її підтвердженням, він видаляється із замовлення. Тоді замовлення переходить у статус OpenPay payment on hold з приміткою, адже покупець оплатив ціну зі знижкою.

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

Модуль приймає лише платежі карткою зі списанням одразу. Він не підтримує збережені картки, підписки, розстрочку без відсотків (MSI) чи оплату частинами, оплату бонусами картки, готівку, SPEI, PSE або CoDi, а також окремі авторизацію та списання.

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

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

Замовлення ще немає: покупець перебуває на сторінці 3D Secure, не завершив оплату або картку відхилено. Існує лише кошик.

Payment accepted: платіж підтверджено. Платіж записується з ID списання OpenPay як ID транзакції, а примітка показує ID списання та режим (робочий або пісочниця).

Awaiting OpenPay payment: OpenPay повідомляє, що списання виконується (ще не зафіксовано). Замовлення переходить у Payment accepted, коли списання завершено, або в Payment error, якщо воно не вдалося.

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

Payment error: списання, що виконувалося, не вдалося, було скасовано або прострочено.

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

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

Блок оплати OpenPay

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

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

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

OpenPay Colombia не підтримує повернення за картками через API, як і офіційні плагіни OpenPay. Для колумбійських списань блок не пропонує форми повернення; поверніть списання в панелі OpenPay.

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

Повернення та спори, зроблені в панелі OpenPay, надходять через вебхук і додаються до приміток один раз. Статус замовлення та кредитові накладні автоматично не змінюються. За потреби оновіть їх вручну.

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

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

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

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

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

OpenPay не з'являється на оформленні замовлення: перевірте, що ліцензія активна, що Enable / Disable увімкнено і що в поточному режимі заповнені всі три ключі: ключі пісочниці в режимі пісочниці, ключі робочого режиму в робочому режимі. Перевірте, що валюта кошика приймається Account country (Мексика: MXN, USD; Колумбія: COP, USD; Перу: PEN, USD). Сторінка налаштувань показує попередження в кожному з цих випадків. У Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи клієнтів.

Платіж пройшов, але замовлення не створено: покупець не повернувся зі сторінки 3D Secure, а вебхук не працює. Перевірте, що URL вебхука додано в панелі OpenPay режиму, який ви використовуєте, точно як показано в налаштуваннях, з переліченими вище подіями. Перевірте, що заповнені ключі режиму, у якому здійснено платіж: без них вебхук відповідає not configured, і OpenPay повторює спробу пізніше. Замовлення також створюється, коли покупець повертається до магазину або намагається знову оплатити той самий кошик.

Вебхук відповідає ignored (unknown order): списання створено не цим магазином, наприклад списання іншого магазину на тому самому обліковому записі OpenPay. Нічого не змінюється.

Вебхук відповідає verification failed: не вдалося звернутися до API OpenPay, щоб зчитати списання. OpenPay повторює вебхук.

Вебхук відповідає busy: кошик у той самий момент оновлювався іншим запитом, або замовлення не вдалося створити (наприклад, модуль вимкнено). OpenPay повторює вебхук. Увімкніть Debug log, щоб побачити причину.

Покупець бачить The secure card form could not be loaded: openpay.js або антифрод-бібліотека OpenPay не завантажилися в браузері, або не вдалося створити ID сесії пристрою. Попросіть покупця перезавантажити сторінку і спробувати знову.

Покупець бачить The payment could not be processed right now: OpenPay відхилила запит або не відповіла. Причина є в журналі. Типова причина — неправильні Merchant ID або закритий ключ. Якщо OpenPay не відповіла, перевірте списання в панелі OpenPay, перш ніж покупець заплатить знову.

Покупець бачить This test card cannot be used for real payments: використано тестову картку пісочниці, коли режим пісочниці вимкнено.

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

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

Повернення не виконується з повідомленням The order is being updated right now: вебхук або інший запит у цей момент оновлював замовлення. Повторіть спробу за хвилину.

Видалення

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

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