VibeFox Viva Wallet for OpenCart — Help

Requirements

OpenCart: 3.0.x (tested on 3.0.5.0) or 4.0.2 and later (tested on 4.1.0.3).

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.

Currency: EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK or CHF. The currency the customer has selected in the store must be one of them; in other currencies the payment method is hidden at checkout.

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

Installation

The download is one zip file with the packages for both OpenCart versions. Unpack it on your computer. It contains README.txt, the OpenCart 3 package wcp_viva_gateway-oc3-(version).ocmod.zip and the OpenCart 4 package wcp_viva_gateway.ocmod.zip. Install only the package for your OpenCart version. The license key is the same for both versions.

OpenCart 3

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_viva_gateway-oc3-(version).ocmod.zip. The extension has no OCMOD modifications, so Extensions > Modifications does not need a refresh. Instead of the installer you can copy the contents of the upload folder of this package into the root folder of your store.

2. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Viva Wallet Gateway and click Install (the green + button). Your admin user needs the right to modify the payment extensions list.

3. Click Edit (the pencil button) to open the settings page. Paste your VibeFox license key into License key in the license block at the top of the 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.

OpenCart 4

1. In the admin go to Extensions > Installer, click Upload and choose the file wcp_viva_gateway.ocmod.zip. Do not rename the file: OpenCart 4 takes the extension code from the file name, and a renamed package does not work.

2. The package appears in the list of installed extensions on the same page. Click Install (the green + button) next to it.

3. Go to Extensions > Extensions and choose the type Payments. Find VibeFox Viva Wallet Gateway, click Install (the green + button), then Edit (the pencil button).

4. Enter the license key, the Viva credentials, the payment source and the webhook as in steps 3 to 5 for OpenCart 3. The settings page and its fields are the same in both versions. Only the addresses for the Viva account are different (see Configuration).

A new install starts with the payment method turned off and test mode on.

Configuration

All settings are on the extension page: Extensions > Extensions > Payments > VibeFox Viva Wallet Gateway > Edit. The sections are listed on the left; the Save button under the list saves the whole page. Above the settings 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 store is not supported. While test mode is on it shows Test mode is on: payments go to the Viva demo environment. Without the right to modify the extension the page shows the settings but cannot save them.

When you save, Title must not be empty and must be at most 128 characters long (Enter a title for the payment method (at most 128 characters).), Sort Order must be a whole number (Sort Order must be a whole number.), Total must be a number, 0 or greater (Total: enter a number, 0 or greater.), and the selected geo zone and order statuses must exist; otherwise nothing is saved and the page shows the error. 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, at most 128 characters.

Description: the text shown to the customer at the Confirm Order step, above the confirm button. 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 the Confirm Order step 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.

Sort Order: the position of Viva Wallet among the payment methods at checkout. Leave it empty or enter a whole number; negative numbers are allowed.

Geo Zone: offer Viva Wallet only for payment addresses in the selected geo zone. Default: All zones. Geo zones are set up in System > Localisation > Geo Zones.

Total: the checkout total, in the default currency of the store, that an order must reach before Viva Wallet is offered: a number, 0 or greater. Leave it empty to offer it for any total.

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 store (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: at the end of the Live account section. Tick a saved 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 store to enter in the Viva account. They are built from the storefront address of your OpenCart installation and look like https://your-store/index.php?route=extension/payment/wcp_viva_gateway/success&, https://your-store/index.php?route=extension/payment/wcp_viva_gateway/fail& and https://your-store/index.php?route=extension/payment/wcp_viva_gateway/webhook on OpenCart 3, and https://your-store/index.php?route=extension/wcp_viva_gateway/payment/wcp_viva_gateway.success&, https://your-store/index.php?route=extension/wcp_viva_gateway/payment/wcp_viva_gateway.fail& and https://your-store/index.php?route=extension/wcp_viva_gateway/payment/wcp_viva_gateway.webhook on OpenCart 4. Copy them exactly as the settings show them. The & at the end of the success and fail addresses is needed: Viva adds the transaction to the address, and without it OpenCart answers with a page not found.

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 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 extension 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 extension never trusts the webhook on its own: every payment is verified with the Viva API before the order gets its status. Without the webhook, an order gets its status 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.

Order statuses

OpenCart creates the order at the Confirm Order step without a status (a missing order). The order gets a status only after the Viva payment has been verified. The status fields list your OpenCart order statuses.

Order Status After Payment: which status a paid order gets. It is set at once, with one status change.

Processing Status: the status of a paid order for Default and Processing. Default: Processing.

Complete Status: the status of a paid order for Completed. Default: Complete.

On Hold Status: the status of a paid order for On Hold, and of an order whose Viva payment does not match the order amount or currency (held for review, not paid; the note says why). Default: Pending, because OpenCart has no On hold status. You can create your own status in System > Localisation > Order Statuses and select it here.

Cancelled Order Status: a Viva payment received for an order in this status never reopens it; a note asks you to restore the order or refund the payment. The extension never sets this status. Default: Canceled.

Refunded Status: set after the payment is fully refunded from the order tab. A later payment never reopens such an order either. Default: Refunded.

Advanced Settings

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 rest of the settings is saved, and 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 viva_wp_debug.log.php in the OpenCart logs folder (storage/logs, on OpenCart 4 system/storage/logs). 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 extension removes the gateway settings and the log. Orders and their payment data (Viva payment attempts, refunds) are never deleted. Default: off.

Import / Export

Export: Download JSON saves the settings as a JSON file. The secrets are not exported.

Import: paste previously exported JSON and click Import to restore the settings. The saved secrets are kept.

Checkout

At the Payment Method step the customer chooses the payment method (by default Viva Wallet). At the Confirm Order step the customer sees your description and the note You will be redirected to the secure Viva Wallet payment page (cards, Apple Pay, Google Pay and more). OpenCart creates the order at this step, still without a status. On OpenCart 4 the customer picks the payment method with the Choose button of the payment method block, in the window Payment method options, and clicks Confirm Order at the bottom of the checkout page. When the customer clicks Confirm Order, the extension creates a Viva payment order for the order total in the order currency and sends the customer to the Viva Smart Checkout page, in your Brand Color if one is set. There the customer pays with one of the methods enabled in your Viva account. The customer's e-mail, name, phone, country and store language are passed to Viva. The payment shows in Viva as OpenCart # and the order number, and is described to the customer as Order, the order number, at and your store name. The Viva payment order expires after 30 minutes.

After paying, the customer returns to your store. The order is marked paid only after Viva confirms it: the extension re-reads the transaction from the Viva API, on the return and on the webhook. The order then gets its status the standard OpenCart way, with the usual order e-mails and stock update, and the customer sees the OpenCart order success 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 cart is kept until the payment is confirmed; the webhook sets the order status as soon as Viva confirms it. On OpenCart 4, when the customer comes back from the Viva page, a short intermediate page opens the return address again from your store, so the cart and the customer session are kept.

If the payment fails or the customer cancels on the Viva page, the order stays without a status 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. Each new attempt starts a new Viva payment order. One cart is paid only once: if the cart is already paid by another order of the same checkout, the customer goes straight to the success page. On OpenCart 4 these messages are shown above the checkout page. OpenCart 3 creates a new order every time the Confirm Order step is shown, OpenCart 4 updates the order of the checkout. A change of the cart, including a new quantity, counts as a new cart that needs its own payment.

OpenCart 4 keeps the order in the checkout until the success page is shown. After a failed or cancelled payment the customer pays the same order again with a new Viva payment order. If that order was closed meanwhile (for example you cancelled it), or it was paid for a cart that has changed since, the customer is sent back to the checkout with This order can no longer be paid. Please confirm your order again., and the next Confirm Order pays a new order.

If Viva cannot start the payment, the customer stays at the Confirm Order step with a message above the button: 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 success page 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 also works while the store is in maintenance mode, because OpenCart lets payment extension requests through. On OpenCart 4 a startup action of the extension lets the webhook and the success and fail addresses through.

The extension 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 status (missing order): the customer was sent to Viva and has not paid, the payment failed or was cancelled, or Viva has not finalized the payment yet. The customer can pay again. In Sales > Orders such orders are shown only with the filter Order Status set to Missing Orders. On OpenCart 4.1 such an order can also have the status Voided, which OpenCart sets when the confirm step is shown again; the extension counts it as an order without a status.

Order Status After Payment (default Processing): the payment was confirmed. 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).

On Hold Status after a mismatch (default Pending): Viva reported a different amount or currency than the order total. The order is not marked paid, and the note Viva Wallet payment held for review gives the reason. Compare the payment in the Viva dashboard with the order and fulfil or refund it manually. If a matching payment for the same order arrives later, the order moves to the paid status.

A payment that arrives for an order in Cancelled Order Status or Refunded Status 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, or for another order of a cart that is already paid, the order is not changed; a note on the paid order asks you to refund the duplicate in the Viva dashboard.

Notes are entries in the order History that the customer does not see. The status changes do not notify the customer by themselves; OpenCart sends its usual order e-mail when a paid order first gets its status.

VibeFox Viva Wallet Gateway tab

In Sales > Orders open an order paid with Viva Wallet. At the bottom of the order page, next to History and Additional, the VibeFox Viva Wallet Gateway tab shows the Viva order code, the Transaction ID with a Demo label for demo payments, the Environment / Source Code, the Viva status, the amounts Paid / refunded, the refund form, the refund history, the Viva payment attempts of the order (when there was more than one) and the Viva Wallet notes of the order. The tab is shown to users who have access to the extension.

Refunds

In the VibeFox Viva Wallet Gateway tab enter the Amount (the amount not refunded yet is filled in), optionally a Reason (optional), 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 payment. You need the right to modify the extension (set in System > Users > User Groups). 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 tab 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 Status without notifying the customer and without returning products to stock, like a manual status change. A partial refund does not change the status. An order held for review after a mismatch has no confirmed payment and cannot be refunded from the tab.

Product returns in Sales > Returns 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 extension works with a VibeFox license key from vibefox.net. The license block License — VibeFox Viva Wallet Gateway is the first block on Extensions > Extensions > Payments > VibeFox Viva Wallet Gateway > Edit, 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 store. Below them are the line Product: opencart-payment-viva and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only admin users with the Modify permission for the extension can change the key. The texts of the block follow the admin 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 store address changes, or after you free a domain slot in your account, click Check now. If the license server cannot be reached, the extension keeps working on the last known status.

One key works on one domain: the store address from the OpenCart configuration. Removing the key from the store 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. An admin user who is logged in to the admin in the same browser still sees the payment method in the store, marked (unlicensed — visible to admins only), so you can set up and test the extension before you buy a key. On OpenCart 4 this preview is not available: the store does not see the admin login, so without an active key the payment method is hidden for everybody. After you have opened the Edit page once, a reminder appears on the admin Dashboard. Close it with × to hide it for 7 days. 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 extension keeps working, but updates and support need a renewal. The status is checked again automatically when you open the admin Dashboard or the Edit page: once a day for the first 14 days after the key is entered, then once a week. No cron job is needed. Uninstalling the extension 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 currency selected in the store must be one of EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK or CHF. Also check that the payment address is in the selected Geo Zone and that the order reaches the Total set in the settings. The settings page shows a warning when credentials are missing.

The payment went through, but the order stays without a status: 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 extension needs them to verify the payment. Turn on Debug Logging and look at the Log field. The order also gets its status when the customer returns to the store after paying.

The customer comes back to a page not found: the Success URL or Failure URL of the payment source does not end with &. Copy the paths exactly as the settings show them.

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, or the order status could not be set. 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 stores on the same Viva account are answered with ignored.

The customer sees an error after Confirm Order: look at the Log field on the extension 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 store could not connect to Viva Wallet. This payment method is not available. means the checkout session no longer matches the order: the customer reloads the checkout.

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 store, for example because the payment source of another store points here. Check the Success URL and Failure URL of the payment source.

Order is in the review status after payment: read the notes in the VibeFox Viva Wallet Gateway tab (see Order statuses), then fulfil the order or refund the payment.

No refund form in the tab: the tab says why: the order has no confirmed Viva payment (Transaction ID not found. Cannot process refund.), it is fully refunded, the credentials of the payment's account are missing, or your user group has no right to modify the extension.

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 message of Viva.

Uninstall

Go to Extensions > Extensions, choose the type Payments and click Uninstall (the red − button) next to VibeFox Viva Wallet Gateway. The license key and license status of this extension are always removed. OpenCart always removes its own settings of the extension: Enable/Disable, Sort Order, Geo Zone, Total and the status fields of the Order statuses section, which return to their defaults on a re-install. The cached Viva access tokens and webhook keys are always removed. On OpenCart 4 the event of the extension and its startup action, which lets the webhook and the return addresses through in maintenance mode, are always removed too. If Delete Data on Uninstall is on, the other gateway settings (title, description, test mode, credentials, order status after payment, brand color, logging) and the log are removed. If it is off, they are kept for a later re-install. The Viva payment attempts and refunds are always kept, so orders paid before can still be refunded after a re-install. Existing orders keep their payment notes.

On OpenCart 4, to remove the files of the extension as well, go to Extensions > Installer after the uninstall and click Uninstall (the orange − button) next to VibeFox Viva Wallet Gateway in the list of installed extensions, then Delete (the red bin button) to remove the uploaded package.

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