VibeFox Viva Wallet for WooCommerce — Help

Requirements

WordPress: 6.0 or later.

WooCommerce: 7.0 or later, installed and active. The plugin refuses to activate without it.

PHP: 8.0 or later.

Viva account: a Viva merchant account. You can use a demo account (demo.vivapayments.com) for tests and a live account (www.vivapayments.com) for real payments. Each account has its own credentials. For payments you need the Smart Checkout credentials (Client ID and Client Secret) and the Source Code of a payment source. The Merchant ID and API Key are optional: they are used only to answer the webhook URL verification of Viva.

Store currency: EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK or CHF. In other currencies the payment method is hidden at checkout.

Public HTTPS site: for webhooks, your site must be reachable from the internet over HTTPS.

VibeFox license key: bought on vibefox.net. One key works on one domain.

Installation

1. In WordPress go to Plugins > Add New > Upload Plugin, choose the plugin ZIP file and click Install Now. You can also upload the wcp_viva_gateway folder to /wp-content/plugins/ by FTP.

2. Click Activate.

3. Open the settings: WooCommerce > Settings > Payments > Viva Wallet > Manage, or click Settings under the plugin name on the Plugins page.

4. Enter your VibeFox license key in the license block at the top of the page and click Activate.

5. Enter the credentials of the demo and/or live Viva account and set up the payment source and the webhook (see Configuration).

6. Turn on Enable/Disable. Make a demo payment with a Viva demo card while Test Mode is on, then untick Test Mode to go live.

Configuration

All settings are on one page: WooCommerce > Settings > Payments > Viva Wallet. Above the fields the page warns you when the current mode has no Client ID, Client Secret or Source Code (Viva Wallet is hidden at checkout until the Demo Client ID, Client Secret and Source Code are entered., or Live in live mode) and when the store currency is not supported. While test mode is on it shows Test mode is on: payments go to the Viva demo environment. In the list of payment methods, Viva Wallet is marked as needing setup until the current mode has these three values.

General

Enable/Disable: Enable Viva Wallet payment gateway turns the payment method on or off. Default: off.

Title: the payment method name customers see at checkout. Default: Viva Wallet.

Description: the text shown under the payment method at checkout. Default: Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.

Test Mode: Use the Viva demo environment (demo.vivapayments.com). New payments and API calls use the demo account credentials. No real money is charged, and at checkout the description ends with (Test mode: use Viva demo cards, no real money is charged.) Default: on. Untick it to take real payments with the live account. Payments already made keep being verified and refunded in the environment they were made in.

Demo account (test mode) and Live account

Both sections have the same fields: one set for the demo account, one for the live account. In your Viva account open Settings > API Access and copy the Smart Checkout credentials (Client ID, Client Secret), the Merchant ID and the API Key. The Source Code is in Sales > Online payments > Websites / apps.

Client ID (Demo) / Client ID (Live): the Smart Checkout OAuth 2.0 Client ID of the account. Required.

Client Secret (Demo) / Client Secret (Live): the Smart Checkout OAuth 2.0 Client Secret of the account. Required.

Source Code (Demo) / Source Code (Live): the 4-digit code of the payment source of the account. Its Success URL and Failure URL must point to this store (see below). Required.

Merchant ID (Demo) / Merchant ID (Live): optional. Used only to answer the webhook URL verification of Viva.

API Key (Demo) / API Key (Live): optional. Used only to answer the webhook URL verification of Viva.

Return URLs and webhook

Payment source: in Sales > Online payments > Websites / apps create a payment source for the domain of your store, in each account you use. As Success URL and Failure URL enter the paths after the domain of the two addresses shown in the settings, which look like https://your-site/wc-api/viva_payment_success/ and https://your-site/wc-api/viva_payment_fail/.

Webhook: in Settings > API Access > Webhooks add the URL shown in the settings, which looks like https://your-site/wp-json/wc-viva-gateway/v1/webhook, for these events:

Viva checks the URL before saving it. The plugin answers with the verification key of your account: it fetches the key with the Merchant ID and API Key of the current mode, or uses the key entered below. Webhooks confirm payments even when the customer closes the browser. Viva webhooks are not signed, so the plugin never trusts the webhook on its own: every payment is verified with the Viva API before the order is marked paid. Without the webhook, an order is confirmed only when the customer comes back to the store after paying.

Webhook Verification Key: optional. Leave it empty to fetch the key automatically with the Merchant ID and API Key of the current mode, or paste the verification key of your Viva account here.

Advanced Settings

Order Status After Payment: the order status set after a successful payment. The status is set at once, without a second status change.

Brand Color: a 6-digit HEX color code for the Viva payment page, for example 0000ff. A leading # is removed. Leave empty for the default color. Any other value is rejected on save and the previous value is kept.

Debug Logging: Enable logging writes API requests to WooCommerce > Status > Logs, source wcp_viva_gateway. Keys and customer data are not logged. Errors are always logged, even when this is off. Default: off.

Delete Data on Uninstall: Remove all plugin data when the plugin is deleted. When on, deleting the plugin removes the settings, the payment attempts table and the plugin logs. Order notes and order data stay. Default: off.

Checkout

The customer chooses the payment method (by default Viva Wallet) and places the order. The plugin creates a Viva payment order for the order total in the order currency and sends the customer to the Viva Smart Checkout page. There the customer pays with one of the methods enabled in your Viva account, such as cards, Apple Pay or Google Pay. The customer's e-mail, name, phone and country are passed to Viva, and the page opens in the language of your site if Viva supports it, otherwise in English. The payment shows in Viva as WooCommerce # and the order number. The Viva payment order expires after 30 minutes.

After paying, the customer returns to the order received page of your store. The order is marked paid only after Viva confirms it: the plugin re-reads the transaction from the Viva API, on the return and on the webhook. If the payment is not confirmed yet, the page shows We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed.

If the payment fails or the customer cancels on the Viva page, the order status does not change. The customer is sent to the Pay for order page with The Viva Wallet payment was not completed. Please try again or choose another payment method. or The Viva Wallet payment was cancelled. You can try again or choose another payment method. and can pay again.

If Viva cannot start the payment, the customer sees Viva Wallet payments are not available at the moment. Please choose another payment method or contact us. (missing or wrong credentials) or We could not connect to Viva Wallet. Please try again in a moment or choose another payment method. The technical reason is written to the log.

The payment method works on the classic checkout, on the Checkout block and on the Pay for order page, where the currency of that order is checked. It is compatible with WooCommerce High-Performance Order Storage (HPOS).

The plugin takes one-time payments only, charged at once on the Viva page. It has no pre-authorization and capture, installments, saved cards, WooCommerce Subscriptions, Viva Native Checkout (card fields on your own page) or POS terminals. When the customer starts a new attempt, the old unpaid Viva payment order is not cancelled; Viva expires it after 30 minutes.

Orders and refunds

Order statuses

Pending payment: the customer was sent to Viva and has not paid yet, the payment was not confirmed yet, or the payment failed or was cancelled. A note shows the Viva payment order and the environment (demo or live). Failed and cancelled attempts are added to the order notes, and the customer can pay again.

Processing, Completed or On Hold: the payment was confirmed. The status follows Order Status After Payment. The order note shows the amount, the Viva transaction ID, the environment and how it was confirmed (webhook or customer return).

On hold for review: Viva reported a different amount or currency than the order total, for example when the order was edited after the customer started paying. The note Viva Wallet payment held for review gives the reason. Compare the payment in the Viva dashboard with the order and complete or refund it manually.

A payment that arrives for a cancelled or refunded order does not change the order status; a note asks you to restore the order or refund the payment in the Viva dashboard. If a second payment arrives for an order that is already paid, the order is not changed again; a note asks you to refund the duplicate in the Viva dashboard.

Refunds

Open the order, click Refund, enter the amount and click Refund via Viva Wallet. Full and partial refunds are supported for orders with a confirmed Viva transaction. The refund is sent to the account the payment was made in (demo or live), in the currency of the payment, so the Client ID and Client Secret of that account must be entered. If Viva does not accept the refund, WooCommerce shows the error and no refund is recorded. A successful refund is added to the order notes with the Viva refund transaction.

Refunds made in the Viva dashboard are not imported. If needed, create a manual refund in WooCommerce without Refund via Viva Wallet.

License key

The plugin works with a VibeFox license key from vibefox.net. The license block is at the top of WooCommerce > Settings > Payments > Viva Wallet. Paste the key into License key and click Activate. The block shows the status, for example the date the license is active until and your domain. Use Check now to check the status again, Change key to enter another key and Remove key to remove it from this site. The link Manage licenses and domains in your account opens your vibefox.net account.

One key works on one domain. Removing the key from a site does not free its domain slot. Free the slot in your vibefox.net account.

Without an active key, Viva Wallet is not shown to customers at checkout. If a payment is started anyway, the customer sees This payment method is not available. Please choose another one. Logged-in store managers still see the payment method, marked (unlicensed — visible to admins only), so you can set up and test the plugin before you buy a key. A reminder appears on the Plugins page and on WooCommerce pages. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the plugin keeps working, but updates and support need a renewal. The status is checked again automatically in the background.

Troubleshooting

Viva Wallet does not appear at checkout: check that the license is active, Enable/Disable is on and the current mode has its Client ID, Client Secret and Source Code (the Demo fields in test mode, the Live fields in live mode). The store currency (on the Pay for order page, the order currency) must be one of EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK or CHF. The settings page shows a warning when something is missing.

The payment went through, but the order stays Pending payment: the webhook is not working. In Viva check that the webhook exists in the account you use (demo or live), that its URL is exactly the one shown in the settings and that Transaction Payment Created is selected. Check that the Client ID and Client Secret of the account of that payment are still entered: the plugin needs them to verify the payment. Details are in WooCommerce > Status > Logs, source wcp_viva_gateway.

Viva cannot verify the webhook URL: enter the Merchant ID and API Key of the current mode (or the verification key itself in Webhook Verification Key), save, then verify again in Viva. To verify the webhook of the other account, switch Test Mode first or enter that account's key.

Webhook answers with an error: Viva shows the answer of your store and retries failed webhooks. verification_failed (HTTP 500) means the Viva API could not be reached to verify the payment. busy (HTTP 503) means the order was being processed by another request at the same moment. transaction_not_found (HTTP 404) means the transaction does not exist in the account of that payment, for example because of wrong credentials. Events for payments of other shops on the same Viva account are answered with ignored.

The customer sees an error when placing the order: turn on Debug Logging and look at WooCommerce > Status > Logs, source wcp_viva_gateway. A wrong Client ID or Client Secret or a missing Source Code gives the message that Viva Wallet payments are not available. If Viva cannot be reached or refuses the payment order, for example because the Source Code belongs to another account, the customer gets the message that the store could not connect to Viva Wallet.

Order is On hold after payment: read the order note. The paid amount or currency differed from the order. Complete the order or refund the payment.

Refund fails with This payment was made in the Viva demo (or live) environment: the Client ID and Client Secret of the account the payment was made in are not entered. Enter them and try again. Other refund errors show the HTTP code and the message of Viva.

The license block shows an error: follow the message in the block. For example, if the key is already used on another domain, free a slot in your vibefox.net account and click Check now. If the site address changed, click Check now to activate the key for the new domain. If the license server cannot be reached, the plugin keeps working on the last known status.

For developers: the filter viva_wp_supported_currencies enables further currencies supported by your Viva account, viva_wp_create_order_payload changes the payment order request (amount, currency and Source Code must stay), and viva_wp_icon changes the checkout icon.

Uninstall

Deactivating the plugin keeps all data; only the cached Viva access tokens are removed. To remove it, deactivate and delete it on the Plugins page. The license key and license status of this plugin and the cached tokens and webhook keys are always removed. The settings, the payment attempts table and the plugin logs (log files, including rotated ones, and database log entries) are removed only if Delete Data on Uninstall was on. Otherwise they stay for a later re-install. Existing orders keep their payment notes and transaction IDs.

Viva Wallet is a trademark of its respective owner. This plugin is not affiliated with or endorsed by Viva Wallet.