VibeFox Viva Wallet for Adobe Commerce — Допомога

Requirements

Magento: Magento Open Source or Adobe Commerce 2.4.6 to 2.4.9, on your own server or hosting, on premises or on Adobe Commerce on cloud infrastructure. The module does not work with Adobe Commerce as a Cloud Service (the SaaS edition), which does not accept PHP modules.

PHP: 8.1 to 8.4, with the cURL and JSON extensions.

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: the order currency (the currency the customer sees at checkout) must be 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

The module is one ZIP file. It is a Composer package and can also be copied into app/code. Run the commands in the Magento root folder as the user that owns the Magento files.

1. With Composer: put the ZIP file into a folder that your project uses as a Composer "artifact" repository and run composer require vibefox/module-viva-payment. Without Composer: unpack the ZIP file into app/code/Vibefox/VivaPayment/, so that registration.php is directly in that folder.

2. Run bin/magento module:enable Vibefox_VivaPayment and bin/magento setup:upgrade. In production mode also run bin/magento setup:di:compile and bin/magento setup:static-content:deploy, then bin/magento cache:flush.

3. In the Admin go to Stores > Configuration > Sales > Payment Methods and open Viva Wallet. When the Magento PayPal module is enabled, the group is listed under Other Payment Methods. Paste your VibeFox license key into License key in the license block, the first row of the group, and click Activate (see License key).

4. Enter the credentials of the demo and/or live Viva account, set up the payment source and the webhook in your Viva account (see Configuration), set Enable to Yes and click Save Config. Make a demo payment with a Viva demo card while Test Mode is Yes, then set Test Mode to No to go live.

The module adds the Viva Wallet payment method to the Magento checkout. It is off after installation (Enable = No). The module uses the standard Magento order states and creates no order statuses of its own. It creates two tables for the Viva payment attempts and refunds.

Configuration

All settings are in Stores > Configuration > Sales > Payment Methods > Viva Wallet, in the standard Magento configuration form. Like other Magento settings, they can be changed for a website with the Scope switcher at the top of the page; Title and Description also for a store view. Remove Data on Uninstall is read from the Default Config only. Save Config saves the whole page. Saving the page also removes the cached Viva access tokens and webhook keys, so new credentials are used at once.

If a value is wrong, Magento shows an error and nothing on the page is saved: an empty Title or a title longer than 128 characters (Enter a title for the payment method (1 to 128 characters).); a Sort Order that is not a whole number; a Min Order Total or Max Order Total that is not a number of 0 or greater, written with a dot as the decimal separator, such as 9.99.

The first part of the group shows the addresses to enter in your Viva account (see Return URLs and webhook). When Enable is Yes, it also shows the state of the current mode: Enter Client ID, Client Secret and Source Code to make Viva available. when the credentials of the current mode are missing, otherwise TEST MODE — payments use the Demo account. or Payments use the Live account. When the default display currency of the store is not supported, it shows Store currency, the currency code and is not supported by Viva. Use a supported checkout currency.

General

Enable: shows or hides Viva Wallet at checkout. It is shown only when the Client ID, Client Secret and Source Code of the current mode are set. Default: No.

Title: the payment method name customers see at checkout. It is also stored in the order. Default: Viva Wallet. Required, at most 128 characters.

Description: the text shown under the payment method when the customer selects it 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) and the Demo fields below. No real money is charged, and at checkout customers see TEST MODE — no real charges will be made. Default: Yes. Set it to No to take real payments with the Live fields. Payments already made keep being verified and refunded in the environment they were made in.

Demo account and Live account

Both accounts have the same fields: the fields marked (Demo) are used in test mode, the fields marked (Live) in live mode. 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 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.

Magento stores the Client Secrets, API Keys and the Webhook Verification Key encrypted and shows only a mask (******) after saving. Leave the mask as it is to keep the saved value, type a new value to change it. To delete a saved secret, clear the field and click Save Config.

Return URLs and webhook

Addresses for the Viva account: the first part of the group shows Success URL, Failure URL and Webhook URL, the storefront addresses of the default store view (or of the store view or website selected in Scope). They look like https://your-store/wcpvivagateway/checkout/back, https://your-store/wcpvivagateway/checkout/fail and https://your-store/wcpvivagateway/checkout/notify. 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 store, in each account you use. As Success URL and Failure URL enter the paths after the domain of the success and failure 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 uses the key entered in Webhook Verification Key, or fetches the key with the Merchant ID and API Key of the current mode. The verification reads the settings of the store view the webhook URL belongs to, so enter these values in the Default Config or for the website of the default store view. 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, with the credentials of the account the payment was made in, before the order is invoiced. 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 with the Merchant ID and API Key, or paste the verification key of your Viva account here. This key only verifies the URL; incoming events are verified by reading the transaction from the Viva API.

Payment page and orders

Brand Color: a 6-digit HEX color code for the Viva payment page, for example 0000ff. A leading # is removed. Leave it empty for the default color. Any other value is not saved; the previous color is kept, the other settings are saved and the page shows Brand Color must be a 6-digit HEX code. The previous value was kept.

Order Status After Payment: what happens to the order after a successful payment.

Advanced

Debug Logging: writes Viva requests to var/log/viva_wp_debug.log.php in the Magento folder. The file cannot be opened from the web and is rotated at 5 MB. Keys, tokens and customer data are not logged. Errors are always logged, even when this is No. Default: No.

Remove Data on Uninstall: when Yes, uninstalling the module with its data deletes the settings and the log (see Uninstall). The cached access tokens and the license key are always removed. The Viva payment attempts and refunds always stay. Default: No.

Conditions

Payment from Applicable Countries: All Allowed Countries offers Viva Wallet for every country your store allows, Specific Countries only for the countries below.

Payment from Specific Countries: offer Viva Wallet only for billing addresses in these countries.

Sort Order: the position among the payment methods at checkout. A whole number.

Min Order Total: offer Viva Wallet only from this order total, in the base currency of your store. Empty means no minimum.

Max Order Total: offer Viva Wallet only up to this order total, in the base currency. Empty means no maximum.

At the end of the group the log viewer shows the size and the latest entries of the log. Click Clear log to empty it.

Checkout

At the payment step the customer chooses the payment method (by default Viva Wallet) and sees the description and the note You will be redirected to Viva to complete your payment. After Place Order, Magento places the order in Pending Payment. No invoice is created and no order e-mail is sent yet. The module then 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. The customer's e-mail, name, phone and country are passed to Viva, and the page opens in the language of the store view if Viva supports it (otherwise in English). The payment shows in Viva as Order #, the order number and the name of your store. 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 module re-reads the transaction from the Viva API, on the return and on the webhook. Magento then creates the invoice with the Viva transaction ID, sets the status from Order Status After Payment and sends the order e-mail. The customer sees the standard order success page. If Viva has not finalized the payment yet, a Viva payment status page shows Waiting for Viva payment confirmation. with the link Check again; the webhook confirms the order as soon as Viva confirms the payment. A customer who comes back in another browser lands on the home page.

If the payment fails or the customer cancels on the Viva page and returns through the Failure URL, the order is cancelled (the stock goes back), the cart is restored and the customer is back in the cart and can pay again. A failed payment reported by the webhook also cancels the waiting order.

If Viva cannot start the payment, for example because of wrong credentials, a Source Code of another account or when Viva cannot be reached before the payment order is sent, the order is cancelled (the stock goes back), the cart is restored and the customer sees Viva could not start the payment. Please try again or choose another payment method. in the cart. The customer can pay again. The technical reason is written to the log.

When Viva did not answer clearly whether the payment order was created, the customer is back on the cart page with Viva could not start payment. Review the payment attempt before retrying., the order stays in Pending Payment and a new Viva payment for the same cart is refused until you have checked the attempt. Such an order is cancelled in Magento or by the Magento cron after the Pending Payment Order Lifetime (Stores > Configuration > Sales > Sales > Orders Cron Settings). An order that is being confirmed at that moment is skipped by the cron and cancelled on its next run.

The module works with the standard Magento checkout. It 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. Viva Wallet is not offered for orders created in the Admin.

Orders and refunds

Order statuses

Pending Payment: the order was placed and the customer was sent to Viva, but Viva has not confirmed the payment yet. There is no invoice.

Processing, Complete or On Hold: the payment was confirmed. The status follows Order Status After Payment. The invoice is created with the Viva transaction ID as the transaction ID, and the note Viva payment accepted after authenticated API verification. is added.

On Hold after a mismatch: Viva reported a different amount or currency than the order total. No invoice is created, and the note says Viva amount/currency mismatch. Money received; manual review required. Compare the payment in the Viva dashboard with the order, then fulfil the order or refund the payment in the Viva dashboard. If a matching payment of the same Viva payment order arrives later, the hold is released and the order is invoiced.

Canceled: the customer cancelled or did not complete the payment, Viva reported a failed payment, or the order was cancelled in Magento or by the cron. A payment that arrives after the order stopped waiting does not reopen it; the note asks you to review or refund it manually. If a second payment arrives for a cart that is already paid, the order is not changed and a note asks you to review and refund the other transaction manually.

Closed: the payment was fully refunded with a credit memo.

The notes are order comments that the customer does not see.

Viva payment information

On the admin order page (Sales > Orders > View) the payment information shows the payment method title and, for each payment attempt, a Viva attempt # line with the Viva order code, the transaction ID, the Source Code, the environment (demo or live), the state of the attempt and the amount, and a Viva refund # line for each refund with the Viva refund transaction, the amount and its state. The information is shown also when the module is disabled. On the storefront the customer sees only the payment method title.

Refunds

Open the order, go to the Invoices tab, open the invoice and click Credit Memo. Choose the items and amounts to refund and click Refund. The money is sent back through Viva. Full and partial refunds are supported. A credit memo started from the order page instead of the invoice offers only Refund Offline, which does not send money back through Viva.

The refund is made in the order currency, up to the amount Viva charged minus the amounts already refunded. It is sent to the account the payment was made in (demo or live), with the Source Code of the payment, so the Client ID and Client Secret of that account must be entered. When they are missing or Viva cannot be reached before the refund is sent, Magento shows The Viva refund was not sent: check the Client ID and Client Secret of the demo or live account the payment was made in., the credit memo is not created and you can refund again later. If Viva does not accept the refund, Magento shows Viva did not confirm the refund. Review it before retrying. and the credit memo is not created. A full refund closes the order. Refunds are available once Viva has confirmed the payment and the order has an invoice.

When Viva did not answer clearly whether a refund was made, the module refuses further online refunds of the order with A previous Viva refund is unconfirmed. Reconcile it before retrying., so money is not sent back twice. Check the refund in the Viva dashboard and record it with Refund Offline. Refunds made in the Viva dashboard are not imported; update the order with Refund Offline if needed.

License key

The module works with a VibeFox license key from vibefox.net. The license block License — Viva Wallet is the first row of the Viva Wallet group in Stores > Configuration > Sales > Payment Methods, 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: magento-payment-viva and the link Manage licenses and domains in your account, which opens your vibefox.net account. Only Admin users whose role allows the Payment Methods configuration section can change the key. The texts of the block follow the Admin interface locale (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 module keeps working on the last known status.

One key works on one domain: the domain of the default store view, also when the installation has several websites or stores. 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 order is cancelled, the cart is restored and the customer sees This payment method is not available. Please choose another one. The Magento storefront does not know that you are logged in to the Admin, 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 the System Messages of the Admin, with the links Enter the license key and Dismiss, which hides it for 7 days. Existing orders are not affected: payments already started are still confirmed, and refunds work.

When a license expires, the module keeps working, but updates and support need a renewal. The status is checked again automatically: once a day for the first 14 days after the key is entered, then once a week, by the Magento cron and while you work in the Admin. Uninstalling the module with its data always removes the license key and license status.

Troubleshooting

Viva Wallet does not appear at checkout: check that the license is active and Enable is Yes for the website of the store, and that 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 settings page shows a warning when they are missing. The currency the customer sees must be one of EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK or CHF, and the order total must be above zero. Check Payment from Applicable Countries and Payment from Specific Countries against the customer's billing address, and Min Order Total and Max Order Total.

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 Webhook URL 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 viewer. The order is also confirmed when the customer returns to the store 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) in the Default Config or for the website of the default store view, click Save Config, 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 unavailable (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 stores on the same Viva account are answered with Unknown.

Webhooks fail while the store is in maintenance mode: Magento maintenance mode closes the whole site, the webhook URL too. Viva retries the webhook later, and the order is also confirmed when the customer returns.

The customer is back in the cart with Viva could not start the payment: turn on Debug Logging and look at the log viewer. Usual reasons are a wrong Client ID or Client Secret, or a Source Code of another account. The order of that attempt is cancelled.

The customer is back on the cart page with Viva could not start payment. Review the payment attempt before retrying.: Viva did not answer clearly whether the payment order was created. Check the payment in the Viva dashboard; the order stays in Pending Payment until you or the cron cancel it.

The customer sees An earlier attempt for this cart requires review: an earlier Viva payment of the same cart has an unclear or mismatched result. Check the payment in the Viva dashboard and the payment information of the earlier order.

Order is On Hold after payment: read the order notes (see Order statuses), then fulfil the order or refund the payment.

Refund fails: The Viva refund was not sent means the Client ID and Client Secret of the account the payment was made in (demo or live) are missing or not accepted, or Viva could not be reached; enter them and try again. No accepted Viva payment found. means the order has no confirmed Viva payment, for example after an amount mismatch; refund the payment in the Viva dashboard. Refund exceeds the remaining payment or has an invalid amount/currency. means the credit memo is larger than the amount left to refund. A previous Viva refund is unconfirmed. Reconcile it before retrying. and An accepted Viva refund has no credit memo. Reconcile it before requesting another refund. mean that an earlier refund must be checked in the Viva dashboard first.

The Refund button is missing on the credit memo: start the credit memo from the invoice (Invoices tab), not from the order page. An order without an invoice (for example On Hold after a mismatch) cannot be refunded online; refund it in the Viva dashboard.

The settings page or the checkout looks unchanged after installing or updating: run bin/magento setup:upgrade and bin/magento cache:flush; in production mode also setup:di:compile and setup:static-content:deploy.

Uninstall

Deleting the module code alone removes nothing from the database: the license key and the settings stay. To remove the data, uninstall the module with the Magento command:

Installed with Composer: run bin/magento module:uninstall --remove-data Vibefox_VivaPayment. It removes the data and the code.

Installed in app/code: run bin/magento module:uninstall --non-composer Vibefox_VivaPayment to remove the data, then bin/magento module:disable Vibefox_VivaPayment, delete the folder app/code/Vibefox/VivaPayment and run bin/magento setup:upgrade.

The license key and license status are always removed. The cached access tokens and webhook keys are always removed. If Remove Data on Uninstall is Yes, the settings and the log are removed too. If it is No, the settings are kept for a 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 invoices, 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.