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 и не одобрен ею.