VibeFox Viva Wallet for PrestaShop — Help

Requirements

PrestaShop: 8.0 to 9.x.

PHP: 8.0 or later. The module refuses to install on older PHP versions.

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.

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

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

Installation

1. In the back office go to Modules > Module Manager and click Upload a module. Choose the module ZIP file.

2. When the upload finishes, click Configure, or find VibeFox Viva Wallet Gateway in the module list later and click Configure.

3. Paste your VibeFox license key into License key in the license block at the top of the Configure page and click Activate (see License key).

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

5. Turn on Enable/Disable and click Save. Make a demo payment with a Viva demo card while Test Mode is on, then turn off Test Mode to go live.

On install the module creates the order status Viva Wallet payment on hold. The module is offered for the countries active at installation. You can change currencies, countries and customer groups in Payment > Preferences; add new countries there later.

Configuration

All settings are on the module page: Modules > Module Manager > VibeFox Viva Wallet Gateway > Configure. Each section has its own Save button, which saves the whole page. 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 default currency of the shop is not supported. While test mode is on it shows Test mode is on: payments go to the Viva demo environment. Saving the settings removes the cached Viva access tokens, so new credentials are used at once.

Viva Wallet

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. It is also the payment method name stored in the order. Default: Viva Wallet. Required: an empty title is not saved and the page shows Enter a title for the payment method.

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: uses 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 customers see (Test mode: use Viva demo cards, no real money is charged.) Default: on. Turn it off 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 for payments.

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

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 shop (see below). Required for payments.

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.

Saved Client Secrets and API Keys are never shown again. The field stays empty and shows Saved — leave empty to keep it. Type a new value only to change it.

Clear saved secrets: tick a secret and click Save to remove it. An empty field keeps the saved value.

Return URLs and webhook

Addresses for the Viva account: this field shows the three addresses of your shop to enter in the Viva account. With friendly URLs they look like https://your-shop/module/wcp_viva_gateway/success, https://your-shop/module/wcp_viva_gateway/fail and https://your-shop/module/wcp_viva_gateway/webhook, possibly with a language code such as /en/. Copy them exactly as the settings show them.

Payment source: in Sales > Online payments > Websites / apps create a payment source for the domain of your shop, in each account you use. As Success URL and Failure URL enter the paths after the domain of the success and fail addresses.

Webhook: in Settings > API Access > Webhooks add the webhook address for these events:

Viva checks the URL before saving it. The module 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 module never trusts the webhook on its own: every payment is verified with the Viva API before the order is created. Without the webhook, an order is created only when the customer comes back to the shop 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 not saved: the page shows Brand Color must be a 6-digit HEX code (e.g. 0000ff). The previous value was kept.

Debug Logging: writes API requests to logs/viva_wp_debug.log.php in the module folder. The file cannot be opened from the web. Keys, tokens and customer data are not logged. Errors are always logged, even when this is off. Default: off.

Log: shows the size and the latest entries of the log. Click Clear log to empty it.

Delete Data on Uninstall: when on, uninstalling the module removes the settings and the module logs. Orders and their payment data (Viva payment attempts, refunds, the order status) are never deleted. Default: off.

Checkout

At the payment step the customer chooses the payment method (by default Viva Wallet) and sees the note You will be redirected to the secure Viva Wallet payment page (cards, Apple Pay, Google Pay and more). After confirming, the module creates a Viva payment order for the cart total in the cart 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. The customer's e-mail, name, phone and country are passed to Viva, and the page opens in the language of the cart if Viva supports it. The payment shows in Viva as Cart #, the cart number and your shop name. The Viva payment order expires after 30 minutes. No order exists yet at this point.

After paying, the customer returns to your shop. The order is marked paid only after Viva confirms it: the module re-reads the transaction from the Viva API, on the return and on the webhook. The order is then created and the customer sees the standard order confirmation page. If the payment is not confirmed yet, a Payment confirmation page shows We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed. with the buttons Check again and Back to checkout; the webhook creates the order as soon as Viva confirms the payment.

If the payment fails or the customer cancels on the Viva page, no order is created and the cart is kept. The customer is back at checkout 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 stays at checkout with 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 return pages show the order confirmation only to the customer who paid. Anyone else who opens the return address is sent to the order history or the checkout without order details.

The webhook works while the shop is in maintenance mode and is not blocked by the country restriction of your shop.

The module takes one-time payments only, charged at once on the Viva page. It has no pre-authorization and capture, installments, saved cards, 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

No order yet: the customer was sent to Viva and has not paid, the payment failed or was cancelled, or Viva has not finalized the payment yet. Only the cart exists, and the customer can pay again.

Payment accepted, Delivered or Viva Wallet payment on hold: the payment was confirmed. The status follows Order Status After Payment. The payment is recorded with the Viva transaction ID, and a note shows the amount, the transaction, the Viva order code, the environment (demo or live) and how it was confirmed (webhook or customer return).

Viva Wallet payment on hold after a mismatch: Viva reported a different amount or currency than the cart total, for example when the cart was changed after the customer started paying. The order is created without a recorded payment, and the note Viva Wallet payment held for review gives the reason. The customer sees the standard order confirmation page without a promise of a Viva confirmation. Compare the payment in the Viva dashboard with the order and fulfil or refund it manually. If a matching payment of the same cart arrives later, the order moves to the paid status.

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; a note asks you to refund the duplicate in the Viva dashboard.

Viva Wallet payment block

The order page shows a Viva Wallet payment block with the Viva order code, the transaction ID, the environment and Source Code, the Viva status, the paid and refunded amounts, a Demo badge for demo payments, the refund history, the payment attempts of the cart (when there was more than one) and the Viva Wallet notes of the order.

Refunds

In the Viva Wallet payment block enter the amount (the amount not refunded yet is filled in), optionally a reason, and click Refund via Viva Wallet. Confirm the question Refund this amount via Viva Wallet? This cannot be undone. Full and partial refunds are supported for orders with a confirmed Viva transaction. You need the right to edit orders; access to the modules is not needed. You can refund up to the amount Viva charged for the payment, even if the order was edited later. 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, the block shows the error and no refund is recorded. A successful refund is added to the refund history and the notes with the Viva refund transaction. A full refund sets the order to Refunded. A partial refund does not change the status. An order held for review without a confirmed payment cannot be refunded from the block.

The module does not create credit slips. The standard PrestaShop refund buttons of the order page do not send money back through Viva. Refunds made in the Viva dashboard are not imported. Update the order manually if needed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — VibeFox Viva Wallet Gateway is the first block on Modules > Module Manager > VibeFox Viva Wallet Gateway > Configure, above the settings. Paste the key into License key and click Activate. After that the block shows the key masked, the status (for example the date the license is active until and your domain) and the buttons Check now to check the status again, Change key to enter another key and Remove key to remove the key from this shop. Below them are the line Product: presta-payment-viva and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only employees with the Configure permission for the module can change the key. The texts of the block follow the back office language (English and Russian are included).

If the key is not accepted, the block says why, for example Key not found, This key belongs to another product, Domain limit reached or License expired on a date. After the shop address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the module keeps working on the last known status.

One key works on one domain: the domain of the main shop, also in a multistore setup. Removing the key from the shop 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. The PrestaShop storefront does not know that you are logged in to the back office, so the payment method is hidden for you too: you can set up the module before you buy a key, but not test it at checkout. A reminder appears in Modules > Module Manager on the Alerts tab. Existing orders are not affected: payments already started are still confirmed by the Viva webhook and the return to the shop, and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically while you work in the back office: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling or resetting the module always removes the license key and license status.

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 cart currency must be one of EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK or CHF. In Payment > Preferences check that the module is allowed for the cart currency, the customer's country and the customer's group. The settings page shows a warning when credentials are missing.

The payment went through, but no order was created: 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 module needs them to verify the payment. Turn on Debug Logging and look at the Log field. The order is also created when the customer returns to the shop after paying.

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 shop and retries failed webhooks. verification_failed (HTTP 500) means the Viva API could not be reached to verify the payment, or the order could not be created (for example, the module is disabled). 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 choosing Viva Wallet: look at the Log field on the module page. A wrong Client ID or Client Secret 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 shop could not connect to Viva Wallet.

The customer returns and sees We could not find your order. If you were charged, please contact us.: the Viva order code in the return address is not a payment of this shop, for example because the payment source of another shop points here. Check the Success URL and Failure URL of the payment source.

Order is Viva Wallet payment on hold after payment: read the notes in the Viva Wallet payment block (see Order statuses), then fulfil 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 block says Transaction ID not found. Cannot process refund.: the order has no confirmed Viva payment, for example after an amount mismatch. Refund the payment in the Viva dashboard if needed.

Uninstall

Disabling the module keeps all data; only the cached Viva access tokens are removed. To remove it, go to Modules > Module Manager, open the menu next to VibeFox Viva Wallet Gateway and choose Uninstall. The license key and license status of this module are always removed. The cached access tokens and webhook keys are always removed. If Delete Data on Uninstall is on, the settings and the log are removed. If it is off, all settings are kept for a later re-install. The Viva payment attempts and refunds and the order status Viva Wallet payment on hold are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes and transaction IDs.

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