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

Вимоги

WordPress: 6.0 або новіша версія.

WooCommerce: 7.0 або новіша, встановлений і активний. Плагін не активується без нього.

PHP: 8.0 або новіша версія.

Обліковий запис 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. В інших валютах спосіб оплати приховується на сторінці оформлення замовлення.

Публічний сайт з HTTPS: для вебхуків ваш сайт має бути доступний з інтернету через HTTPS.

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

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

1. У WordPress перейдіть до Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна і натисніть Install Now. Також можна завантажити папку wcp_viva_gateway до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > Viva Wallet > Manage або натисніть Settings під назвою плагіна на сторінці Plugins.

4. Введіть ліцензійний ключ VibeFox у блоці ліцензії вгорі сторінки та натисніть Activate.

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

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

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

Усі параметри розміщено на одній сторінці: WooCommerce > Settings > Payments > Viva Wallet. Над полями сторінка попереджає, якщо в поточному режимі немає 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 Wallet позначено як такий, що потребує налаштування, доки в поточному режимі немає цих трьох значень.

Загальні

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

Title: назва способу оплати, яку бачать покупці на сторінці оформлення замовлення. За замовчуванням: Viva Wallet.

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

Test Mode: Use the Viva demo environment (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.

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

Payment source: у розділі Sales > Online payments > Websites / apps створіть джерело платежів для домену вашого магазину в кожному використовуваному обліковому записі. Як Success URL і Failure URL вкажіть шляхи після домену з двох адрес, які показано в налаштуваннях і які мають вигляд https://your-site/wc-api/viva_payment_success/ та https://your-site/wc-api/viva_payment_fail/.

Webhook: у розділі Settings > API Access > Webhooks додайте URL з налаштувань, який має вигляд https://your-site/wp-json/wc-viva-gateway/v1/webhook, для таких подій:

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. Початковий символ # видаляється. Залиште порожнім для кольору за замовчуванням. Будь-яке інше значення відхиляється під час збереження, і зберігається попереднє.

Debug Logging: Enable logging записує запити до API в WooCommerce > Status > Logs, джерело wcp_viva_gateway. Ключі та дані покупців не записуються. Помилки записуються завжди, навіть коли опцію вимкнено. За замовчуванням: вимкнено.

Delete Data on Uninstall: Remove all plugin data when the plugin is deleted. Якщо увімкнено, під час видалення плагіна видаляються налаштування, таблиця спроб платежів і журнали плагіна. Нотатки та дані замовлень залишаються. За замовчуванням: вимкнено.

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

Покупець обирає спосіб оплати (за замовчуванням Viva Wallet) і оформляє замовлення. Плагін створює платіжне замовлення Viva на суму замовлення у його валюті та надсилає покупця на сторінку Viva Smart Checkout. Там він платить одним із способів, увімкнених у вашому обліковому записі Viva, наприклад карткою, Apple Pay або Google Pay. E-mail, ім'я, телефон і країна покупця передаються до Viva, а сторінка відкривається мовою вашого сайту, якщо Viva її підтримує, інакше англійською. Платіж відображається у Viva як WooCommerce # і номер замовлення. Платіжне замовлення Viva закривається через 30 хвилин.

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

Якщо платіж не вдався або покупець скасував оплату на сторінці Viva, статус замовлення не змінюється. Покупця перенаправляє на сторінку Pay for order з повідомленням 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. Технічна причина записується в журнал.

Спосіб оплати працює в класичному оформленні замовлення, у блоці оформлення замовлення та на сторінці Pay for order, де перевіряється валюта цього замовлення. Він сумісний з WooCommerce High-Performance Order Storage (HPOS).

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

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

Order statuses

Pending payment: покупця перенаправлено до Viva, і він ще не сплатив, платіж ще не підтверджено, або платіж не вдався чи був скасований. Нотатка показує платіжне замовлення Viva та середовище (демо або робоче). Невдалі та скасовані спроби додаються до нотаток замовлення, і покупець може оплатити знову.

Processing, Completed or On Hold: платіж підтверджено. Статус відповідає Order Status After Payment. Нотатка до замовлення показує суму, ID транзакції Viva, середовище та спосіб підтвердження (вебхук або повернення покупця).

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

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

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

Відкрийте замовлення, натисніть Refund, введіть суму та натисніть Refund via Viva Wallet. Повні та часткові повернення підтримуються для замовлень із підтвердженою транзакцією Viva. Повернення надсилається на обліковий запис, з якого було здійснено платіж (демо або робочий), у валюті платежу, тож мають бути введені Client ID і Client Secret цього облікового запису. Якщо Viva не приймає повернення, WooCommerce показує помилку і повернення не реєструється. Успішне повернення додається до нотаток замовлення разом із транзакцією повернення Viva.

Повернення, зроблені в кабінеті Viva, не імпортуються. За потреби створіть ручне повернення у WooCommerce без Refund via Viva Wallet.

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

Плагін працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії розміщено вгорі сторінки WooCommerce > Settings > Payments > Viva Wallet. Вставте ключ у поле License key і натисніть Activate. Блок показує статус, наприклад дату, до якої ліцензія активна, та ваш домен. Використовуйте Check now, щоб перевірити статус знову, Change key, щоб ввести інший ключ, і Remove key, щоб видалити його з цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис на vibefox.net.

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

Без активного ключа Viva Wallet не показується покупцям на сторінці оформлення замовлення. Якщо платіж усе ж розпочато, покупець бачить This payment method is not available. Please choose another one. Адміністратори магазину, які ввійшли в систему, як і раніше бачать спосіб оплати, позначений (unlicensed — visible to admins only), щоб ви могли налаштувати та протестувати плагін до придбання ключа. Нагадування з'являється на сторінці Plugins і на сторінках WooCommerce. Наявні замовлення не змінюються: платежі, які вже розпочато, як і раніше підтверджуються, а повернення працюють.

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

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

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

Платіж пройшов, але замовлення залишається у статусі Pending payment: вебхук не працює. У Viva перевірте, що вебхук існує в обліковому записі, який ви використовуєте (демо або робочому), що його URL точно збігається з показаним у налаштуваннях і що вибрано Transaction Payment Created. Перевірте, що Client ID і Client Secret облікового запису цього платежу досі введені: плагін використовує їх для перевірки платежу. Деталі — у WooCommerce > Status > Logs, джерело wcp_viva_gateway.

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.

Покупець бачить помилку під час оформлення замовлення: увімкніть Debug Logging і перегляньте WooCommerce > Status > Logs, джерело wcp_viva_gateway. Неправильний Client ID або Client Secret чи відсутній Source Code дають повідомлення, що платежі Viva Wallet недоступні. Якщо Viva недоступна або відхиляє платіжне замовлення, наприклад тому що Source Code належить іншому обліковому запису, покупець отримує повідомлення, що магазину не вдалося підключитися до Viva Wallet.

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

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

Блок ліцензії показує помилку: дотримуйтесь повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть слот в обліковому записі vibefox.net і натисніть Check now. Якщо адреса сайту змінилася, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін продовжує працювати за останнім відомим статусом.

Для розробників: фільтр viva_wp_supported_currencies вмикає додаткові валюти, які підтримує ваш обліковий запис Viva, viva_wp_create_order_payload змінює запит на платіжне замовлення (сума, валюта та Source Code мають залишитися незмінними), а viva_wp_icon змінює іконку на сторінці оформлення замовлення.

Видалення

Деактивація плагіна зберігає всі дані; видаляються лише кешовані токени доступу Viva. Щоб видалити плагін, деактивуйте його та видаліть на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна, а також кешовані токени та ключі вебхуків завжди видаляються. Налаштування, таблиця спроб платежів і журнали плагіна (файли журналів, зокрема ротовані, та записи бази даних) видаляються лише якщо була увімкнена опція Delete Data on Uninstall. Інакше вони зберігаються для повторного встановлення. Наявні замовлення зберігають свої платіжні нотатки та ID транзакцій.

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