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.