VibeFox Viva Wallet for PrestaShop — Допомога

Вимоги

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

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

Обліковий запис Viva: обліковий запис мерчанта Viva. Для тестів можна використовувати демо-обліковий запис (demo.vivapayments.com), для реальних платежів — робочий (www.vivapayments.com). Кожен обліковий запис має власні облікові дані. Для платежів потрібні облікові дані Smart Checkout (Client ID і Client Secret) та Source Code джерела платежів. Merchant ID і API Key необов'язкові: вони потрібні лише для відповіді на перевірку URL вебхука з боку Viva.

Валюта: EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK або CHF. В інших валютах спосіб оплати на етапі оформлення замовлення прихований.

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

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

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

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

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

4. Введіть облікові дані демо- та/або робочого облікового запису Viva, налаштуйте джерело платежів і вебхук у своєму обліковому записі Viva (див. Налаштування).

5. Увімкніть Enable/Disable і натисніть Save. Зробіть демо-платіж демо-карткою Viva, поки увімкнено Test Mode, а потім вимкніть Test Mode, щоб перейти до реальних платежів.

Під час встановлення модуль створює статус замовлення Viva Wallet payment on hold. Модуль пропонується для країн, активних на момент встановлення. Валюти, країни та групи клієнтів можна змінити в Payment > Preferences; нові країни додаються там пізніше.

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Viva Wallet Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, якщо в поточному режимі немає Client ID, Client Secret або Source Code (Viva Wallet is hidden at checkout until the Demo Client ID, Client Secret and Source Code are entered. або Live у робочому режимі), а також якщо валюта магазину за замовчуванням не підтримується. Поки тестовий режим увімкнено, вона показує Test mode is on: payments go to the Viva demo environment. Збереження налаштувань видаляє кешовані токени доступу Viva, тож нові облікові дані використовуються одразу.

Viva Wallet

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

Title: назва способу оплати, яку бачать клієнти на етапі оформлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: Viva Wallet. Обов'язково: порожня назва не зберігається, і сторінка показує Enter a title for the payment method.

Description: текст під способом оплати на етапі оформлення. За замовчуванням: Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.

Test Mode: використовує демо-середовище Viva (demo.vivapayments.com). Нові платежі та виклики API використовують облікові дані демо-облікового запису. Реальні кошти не списуються, а на етапі оформлення клієнти бачать (Test mode: use Viva demo cards, no real money is charged.) За замовчуванням: увімкнено. Вимкніть його, щоб приймати реальні платежі через робочий обліковий запис. Платежі, які вже зроблено, і далі перевіряються та повертаються в тому середовищі, де були зроблені.

Демо-обліковий запис (тестовий режим) і робочий обліковий запис

Обидва розділи мають однакові поля: один набір для демо-облікового запису, інший — для робочого. У своєму обліковому записі Viva відкрийте Settings > API Access і скопіюйте облікові дані Smart Checkout (Client ID, Client Secret), Merchant ID та API Key. Source Code знаходиться в Sales > Online payments > Websites / apps.

Client ID (Demo) / Client ID (Live): OAuth 2.0 Client ID Smart Checkout облікового запису. Обов'язково для платежів.

Client Secret (Demo) / Client Secret (Live): OAuth 2.0 Client Secret Smart Checkout облікового запису. Обов'язково для платежів.

Source Code (Demo) / Source Code (Live): 4-значний код джерела платежів облікового запису. Його Success URL і Failure URL мають вести на цей магазин (див. нижче). Обов'язково для платежів.

Merchant ID (Demo) / Merchant ID (Live): необов'язково. Використовується лише для відповіді на перевірку URL вебхука з боку Viva.

API Key (Demo) / API Key (Live): необов'язково. Використовується лише для відповіді на перевірку URL вебхука з боку Viva.

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

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

URL повернення та вебхук

Addresses for the Viva account: це поле показує три адреси вашого магазину, які потрібно ввести в обліковому записі Viva. З дружніми URL вони виглядають так: https://your-shop/module/wcp_viva_gateway/success, https://your-shop/module/wcp_viva_gateway/fail та https://your-shop/module/wcp_viva_gateway/webhook, можливо з кодом мови, наприклад /en/. Копіюйте їх точно так, як їх показують налаштування.

Payment source: у Sales > Online payments > Websites / apps створіть джерело платежів для домену вашого магазину в кожному обліковому записі, який використовуєте. Як Success URL і Failure URL введіть частини адрес успіху та помилки, що йдуть після домену.

Webhook: у Settings > API Access > Webhooks додайте адресу вебхука для цих подій:

Viva перевіряє URL перед збереженням. Модуль відповідає ключем перевірки вашого облікового запису: він отримує ключ за допомогою Merchant ID та API Key поточного режиму або використовує ключ, введений нижче. Вебхуки підтверджують платежі навіть тоді, коли покупець закрив браузер. Вебхуки Viva не підписуються, тож модуль ніколи не довіряє самому вебхуку: кожен платіж перевіряється через API Viva до створення замовлення. Без вебхука замовлення створюється лише тоді, коли покупець повертається до магазину після оплати.

Webhook Verification Key: необов'язково. Залиште порожнім, щоб отримати ключ автоматично за допомогою Merchant ID та API Key поточного режиму, або вставте сюди ключ перевірки вашого облікового запису Viva.

Додаткові налаштування

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

Brand Color: 6-значний HEX-код кольору для платіжної сторінки Viva, наприклад 0000ff. Початковий # видаляється. Залиште порожнім для кольору за замовчуванням. Будь-яке інше значення не зберігається: сторінка показує Brand Color must be a 6-digit HEX code (e.g. 0000ff). The previous value was kept.

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

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

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Viva Wallet) і бачить примітку You will be redirected to the secure Viva Wallet payment page (cards, Apple Pay, Google Pay and more). Після підтвердження модуль створює платіжне замовлення Viva на суму кошика у валюті кошика і надсилає покупця на сторінку Viva Smart Checkout. Там покупець платить одним із способів, увімкнених у вашому обліковому записі Viva. E-mail, ім'я, телефон і країна покупця передаються до Viva, а сторінка відкривається мовою кошика, якщо Viva її підтримує. У Viva платіж відображається як Cart #, номер кошика та назва вашого магазину. Платіжне замовлення Viva спливає через 30 хвилин. На цьому етапі замовлення ще немає.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження Viva: модуль повторно зчитує транзакцію через API Viva — при поверненні покупця та за вебхуком. Потім замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення. Якщо платіж ще не підтверджено, сторінка Payment confirmation показує We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed. з кнопками Check again та Back to checkout; вебхук створить замовлення, щойно Viva підтвердить платіж.

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

Якщо Viva не може розпочати платіж, покупець залишається на етапі оформлення з повідомленням Viva Wallet payments are not available at the moment. Please choose another payment method or contact us. (облікові дані відсутні або невірні) або We could not connect to Viva Wallet. Please try again in a moment or choose another payment method. Технічна причина записується в журнал.

Сторінки повернення показують підтвердження замовлення лише покупцеві, який оплатив. Будь-хто інший, хто відкриє адресу повернення, перенаправляється в історію замовлень або на оформлення без деталей замовлення.

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

Модуль приймає лише разові платежі, які списуються одразу на сторінці Viva. Він не має попередньої авторизації та списання, розстрочки, збережених карток, підписок, Viva Native Checkout (полів картки на вашій сторінці) чи POS-терміналів. Коли покупець починає нову спробу, старе неоплачене платіжне замовлення Viva не скасовується; Viva спливає його через 30 хвилин.

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

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

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

Payment accepted, Delivered або Viva Wallet payment on hold: платіж підтверджено. Статус відповідає Order Status After Payment. Платіж фіксується з ID транзакції Viva, а нотатка показує суму, транзакцію, код замовлення Viva, середовище (демо або робоче) і спосіб підтвердження (вебхук або повернення покупця).

Viva Wallet payment on hold після розбіжності: Viva повідомила суму або валюту, що відрізняються від суми кошика, наприклад коли кошик було змінено після того, як покупець почав оплату. Замовлення створюється без зафіксованого платежу, а нотатка Viva Wallet payment held for review вказує причину. Покупець бачить стандартну сторінку підтвердження замовлення без обіцянки підтвердження від Viva. Порівняйте платіж у кабінеті Viva із замовленням і виконайте замовлення або поверніть кошти вручну. Якщо пізніше надійде відповідний платіж за тим самим кошиком, замовлення перейде в оплачений статус.

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

Блок Viva Wallet payment

На сторінці замовлення показано блок Viva Wallet payment з кодом замовлення Viva, ID транзакції, середовищем і Source Code, статусом Viva, сумами оплати та повернень, значком Demo для демо-платежів, історією повернень, спробами оплати кошика (якщо їх було більше однієї) та Viva Wallet notes замовлення.

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

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

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

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

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

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

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

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

Viva Wallet не з'являється на етапі оформлення: перевірте, що ліцензія активна, Enable/Disable увімкнено і в поточному режимі заповнені Client ID, Client Secret та Source Code (поля Demo у тестовому режимі, поля Live у робочому режимі). Валюта кошика має бути однією з EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK або CHF. У Payment > Preferences перевірте, що модулю дозволено валюту кошика, країну покупця та групу покупців. Сторінка налаштувань показує попередження, якщо облікові дані не заповнені.

Платіж пройшов, але замовлення не створено: вебхук не працює. У Viva перевірте, що вебхук існує в обліковому записі, яким ви користуєтеся (демо або робочий), що його URL точно збігається з показаним у налаштуваннях і що вибрано Transaction Payment Created. Перевірте, що Client ID і Client Secret облікового запису цього платежу досі введені: модулю вони потрібні для перевірки платежу. Увімкніть Debug Logging і подивіться поле Log. Замовлення також створюється, коли покупець повертається до магазину після оплати.

Viva не може перевірити URL вебхука: введіть Merchant ID та API Key поточного режиму (або сам ключ перевірки в Webhook Verification Key), збережіть і перевірте знову у Viva. Щоб перевірити вебхук іншого облікового запису, спочатку перемкніть Test Mode або введіть ключ цього облікового запису.

Вебхук відповідає помилкою: Viva показує відповідь вашого магазину і повторює невдалі вебхуки. verification_failed (HTTP 500) означає, що до API Viva не вдалося звернутися для перевірки платежу або не вдалося створити замовлення (наприклад, модуль вимкнено). busy (HTTP 503) означає, що замовлення в цей самий момент оброблявся іншим запитом. transaction_not_found (HTTP 404) означає, що транзакції немає в обліковому записі цього платежу, наприклад через невірні облікові дані. Події для платежів інших магазинів у тому самому обліковому записі Viva отримують відповідь ignored.

Клієнт бачить помилку, обираючи Viva Wallet: перегляньте поле Log на сторінці модуля. Невірний Client ID або Client Secret показує повідомлення, що платежі Viva Wallet недоступні. Якщо Viva недоступна або відхиляє платіжне замовлення, наприклад тому що Source Code належить іншому обліковому запису, покупець отримує повідомлення, що магазин не зміг підключитися до Viva Wallet.

Покупець повертається і бачить We could not find your order. If you were charged, please contact us.: код замовлення Viva в адресі повернення не належить до платежу цього магазину, наприклад тому що джерело платежів іншого магазину вказує сюди. Перевірте Success URL і Failure URL джерела платежів.

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

Повернення не проходить з This payment was made in the Viva demo (or live) environment: не введено Client ID і Client Secret облікового запису, в якому було зроблено платіж. Введіть їх і спробуйте знову. Інші помилки повернення показують HTTP-код і повідомлення Viva.

Блок показує Transaction ID not found. Cannot process refund.: у замовлення немає підтвердженого платежу Viva, наприклад після розбіжності суми. За потреби поверніть платіж у кабінеті Viva.

Видалення

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

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