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

Вимоги

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

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

Валюта: колумбійське песо (COP). Wompi Colombia приймає оплату в COP, а спосіб оплати приховано для кошиків в інших валютах. Сторінка налаштувань попереджає, якщо валюта магазину за замовчуванням не COP.

Обліковий запис Wompi: обліковий запис мерчанта Wompi Colombia. Кожне середовище (sandbox і production) має чотири ключі: публічний ключ, приватний ключ, секрет подій і секрет цілісності. Знайти їх можна на панелі мерчанта Wompi (comercios.wompi.co) у розділі для розробників. Wompi El Salvador і Panama використовують інші API і не підтримуються.

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

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

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

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

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

4. Вставте ключі sandbox і production з панелі мерчанта Wompi та вкажіть URL подій у Wompi (див. Налаштування).

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

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

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

Усі налаштування розміщено на сторінці модуля: Modules > Module Manager > VibeFox Wompi Payment > Configure. Кожен розділ із полями має власну кнопку Save, яка зберігає всю сторінку. Над полями блок статусу показує поточний режим, SANDBOX або PRODUCTION. Якщо ключа цього режиму немає, блок його перелічує і повідомляє, що спосіб оплати приховано під час оформлення замовлення, доки не задано всі ключі цього середовища. Коли всі ключі задано, блок повідомляє, чи списуватимуться реальні платежі. Під час збереження модуль попереджає, якщо ключ не починається з префікса свого розділу, і якщо Wompi увімкнено, але приховано під час оформлення замовлення через відсутні ключі.

Wompi

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

Title: назва способу оплати, яку бачать покупці під час оформлення замовлення. Вона також зберігається в замовленні. За замовчуванням: Wompi. Якщо поле залишити порожнім, використовується назва модуля.

Description: текст під способом оплати під час оформлення замовлення. За замовчуванням: Pay securely with Wompi: cards, PSE, Nequi, Bancolombia and more.

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

Скопіюйте ключі з панелі мерчанта Wompi (comercios.wompi.co), розділ для розробників. Кожне середовище має власні публічний ключ, приватний ключ, секрет подій і секрет цілісності.

Sandbox mode: використовує пісочницю Wompi (ключі sandbox, без реальних грошей). Перемикаються і ключі, і API Wompi (sandbox.wompi.co або production.wompi.co). Спроби оплати зберігають середовище, в якому були зроблені. За замовчуванням: on. Вимкніть, щоб приймати реальні платежі. Поки режим увімкнено, покупці бачать під способом оплати Режим sandbox: реальний платіж не здійснюється.

Ключі sandbox

Чотири ключі пісочниці Wompi. Вони починаються з pub_test_, prv_test_, test_events_ і test_integrity_.

Public key: публічний ключ sandbox (pub_test_...). Він ідентифікує ваш обліковий запис у Wompi Web Checkout.

Private key: приватний ключ sandbox (prv_test_...). Використовується для читання транзакцій з API Wompi.

Events secret: секрет подій sandbox (test_events_...). Перевіряє підпис подій Wompi.

Integrity secret: секрет цілісності sandbox (test_integrity_...). Підписує запит на оплату, який надсилається до Web Checkout.

Ключі production

Чотири ключі виробничого середовища Wompi. Вони починаються з pub_prod_, prv_prod_, prod_events_ і prod_integrity_.

Public key: публічний ключ production (pub_prod_...).

Private key: приватний ключ production (prv_prod_...).

Events secret: секрет подій production (prod_events_...).

Integrity secret: секрет цілісності production (prod_integrity_...).

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

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

URL подій (webhook)

Події Wompi повідомляють вашому магазину, що транзакцію змінено. На панелі мерчанта Wompi, у розділі для розробників, вкажіть URL подій, який показано в цьому розділі, — окремо для sandbox і для production. З дружніми URL він виглядає так: https://your-shop/module/wcp_wompi_payment/webhook, можливо з кодом мови, наприклад /es/. Копіюйте URL точно так, як його показують налаштування.

Модуль використовує цю подію:

transaction.updated: транзакцію схвалено, відхилено, анульовано, вона завершилася з помилкою або очікує.

Інші події отримують відповідь Ignored. Кожна подія перевіряється секретом подій свого середовища (sandbox або production). Webhook без коректного підпису відхиляється. Після перевірки транзакція зчитується з API Wompi приватним ключем цього середовища, і використовуються лише ці дані. Без URL подій замовлення створюється лише тоді, коли покупець повертається до магазину після оплати.

Додатково

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

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

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Wompi) і підтверджує. Модуль створює спробу оплати з власним референсом (PS-, номер кошика і позначка часу), підписує її секретом цілісності та надсилає покупця до Wompi Web Checkout із сумою кошика в COP. E-mail покупця та ім'я в адресі для рахунку передаються до Wompi. На цьому етапі замовлення ще не існує.

На сторінці Wompi покупець сплачує будь-яким способом оплати, увімкненим у вашому обліковому записі Wompi. Потім Wompi повертає покупця до вашого магазину. Замовлення позначається оплаченим лише після підтвердження Wompi: підписаною подією або серверним запитом до API Wompi, коли покупець повертається. Номеру транзакції в самій адресі повернення не довіряють, і приймаються лише транзакції, створені для цього кошика в середовищі його спроби. Під час перезавантаження сторінки транзакцію перевіряють знову не частіше ніж раз на 20 секунд.

Коли транзакцію схвалено, замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення. Для платежу в очікуванні (наприклад, PSE, Nequi або готівкою) сторінка показує Ваш платіж Wompi очікує підтвердження (наприклад, PSE, Nequi або готівкою). Ми обробимо замовлення, щойно Wompi підтвердить платіж. Для замовлення на утриманні показується Ми отримали ваш платіж Wompi і перевіряємо його. Ми зв'яжемося з вами, якщо щось знадобиться. Якщо платіж в очікуванні згодом відхиляють, сторінка показує Ваш платіж Wompi не був схвалений. Будь ласка, зв'яжіться з нами. Якщо його анулюють, сторінка показує Ваш платіж Wompi був анульований, і це замовлення скасовано. Будь ласка, зв'яжіться з нами.

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

Якщо платіж відхилено, замовлення не створюється, а кошик зберігається. Покупець повертається до оформлення замовлення з повідомленням Ваш платіж Wompi не був схвалений (...). Ви можете повторити спробу або обрати інший спосіб оплати. з причиною, яку вказав Wompi. Анульований платіж показує Ваш платіж Wompi був анульований. Ви можете повторити спробу або обрати інший спосіб оплати. Якщо покупець покидає Web Checkout без оплати, повідомлення має вигляд Ваш платіж Wompi не був завершений. Ви можете повторити спробу або обрати інший спосіб оплати. Кожна нова спроба отримує новий референс. Щойно в кошика з'являється замовлення (оплачено, в очікуванні, Помилка оплати або Скасовано), його не можна оплатити знову: покупець переходить на сторінку підтвердження замовлення.

Спосіб оплати показується лише тоді, коли ліцензія активна, усі чотири ключі поточного режиму задано, валюта кошика — COP і дозволена для модуля, а сума становить щонайменше COP 1 500. Якщо оплату не вдається розпочати, покупець залишається на оформленні замовлення з коротким повідомленням:

Wompi зараз недоступний. Оберіть інший спосіб оплати.: бракує ключів поточного режиму.

Wompi приймає платежі лише в COP; це замовлення в ...: кошик у іншій валюті.

Мінімальна сума для платежів Wompi — ...: сума кошика менша за COP 1 500.

Цей спосіб оплати недоступний.: модуль вимкнено або він не дозволений для країни, валюти чи групи клієнтів кошика.

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

Модуль не виконує повернення коштів з PrestaShop. На вашому сайті немає збережених карток, підписок і полів для картки: усі платіжні дані вводяться в Wompi.

Замовлення

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

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

Awaiting Wompi payment: Wompi позначає транзакцію як очікувану, наприклад платежі PSE, Nequi або готівкою, що чекають підтвердження. Замовлення чекає, доки Wompi його схвалить або відхилить. Коли платіж схвалено, його фіксують, а замовлення переходить у статус Payment accepted.

Payment accepted: транзакцію схвалено на суму кошика в COP. Платіж фіксується з ID транзакції Wompi, а примітка показує транзакцію, тип способу оплати (наприклад, CARD, PSE або NEQUI), референс, суму та середовище.

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

Payment error: транзакцію в очікуванні останньої спроби оплати відхилено або вона завершилася помилкою. Повідомлення Wompi додається до примітки. Результати попередніх спроб замовлення не змінюють.

Canceled: транзакцію в очікуванні останньої спроби оплати анульовано в Wompi.

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

Блок оплати Wompi

На сторінці замовлення показується блок Wompi payment з референсом, ID транзакції, статусом (зі статусом Wompi), запитаною сумою, сумою транзакції, способом оплати, повідомленням Wompi, позначкою SANDBOX для платежів sandbox, Payment attempts кошика, якщо їх було кілька, і Wompi notes замовлення.

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

Повернення коштів не надсилаються з PrestaShop. Поверніть або анулюйте платіж на панелі мерчанта Wompi, а потім вручну зафіксуйте повернення в PrestaShop. Анулювання транзакції оплати, зроблене в Wompi, додається до замовлення як примітка.

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

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

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

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

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

Wompi не з'являється під час оформлення замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено і всі чотири ключі поточного режиму задано (блок статусу на сторінці налаштувань перелічує відсутні ключі). Перевірте також, що валюта кошика — COP, а сума становить щонайменше COP 1 500. У Payment > Preferences перевірте, що модуль дозволений для COP, країни клієнта та групи клієнта.

Платіж пройшов, але замовлення не створено: URL подій не працює. На панелі Wompi перевірте, що URL подій задано для середовища, яке ви використовуєте (sandbox або production), і що він точно збігається з показаним у налаштуваннях. Перевірте, що секрет подій цього середовища міститься у відповідному розділі. Замовлення також створюється, коли покупець повертається до магазину після оплати.

URL подій відповідає Not configured: секрет подій середовища події порожній. Вставте його в налаштування.

URL подій відповідає Invalid signature: секрет подій належить іншому середовищу або іншому обліковому запису. Скопіюйте його знову з панелі Wompi.

URL подій відповідає Transaction lookup failed: API Wompi не повернув транзакцію, наприклад через неправильний приватний ключ або проблему з мережею. Wompi надішле подію повторно пізніше.

URL подій відповідає Retry: замовлення саме підтверджувалося іншим запитом або замовлення не вдалося створити (наприклад, модуль вимкнено). Wompi надішле подію повторно пізніше. Причину дивіться в полі Log.

URL подій відповідає Environment mismatch: транзакція sandbox прийшла для спроби оплати production або навпаки. Платежі sandbox ніколи не підтверджують замовлення production.

URL подій відповідає Unknown reference: референс транзакції видано не цим магазином, наприклад той самий обліковий запис Wompi використовує інший магазин. Референси інших систем отримують відповідь Ignored.

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

Попередження під час збереження, що ключ не починається з ...: ключ вставлено у неправильний розділ. Ключі sandbox починаються з pub_test_, prv_test_, test_events_ і test_integrity_, ключі production — з pub_prod_, prv_prod_, prod_events_ і prod_integrity_.

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

Інші помилки: дивіться поле Log на сторінці модуля та Wompi notes замовлення. Помилки завжди записуються. Увімкніть Debug log для докладніших відомостей.

Видалення

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

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