VibeFox Viva Wallet for WooCommerce — Aide

Prérequis

WordPress: 6.0 ou ultérieur.

WooCommerce: 7.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP: 8.0 ou ultérieur.

Compte Viva: un compte marchand Viva. Vous pouvez utiliser un compte de démo (demo.vivapayments.com) pour les tests et un compte de production (www.vivapayments.com) pour les paiements réels. Chaque compte a ses propres identifiants. Pour les paiements, vous avez besoin des identifiants Smart Checkout (Client ID et Client Secret) et du Source Code d'une source de paiement. Le Merchant ID et l'API Key sont facultatifs : ils ne servent qu'à répondre à la vérification de l'URL du webhook par Viva.

Devise de la boutique: EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK ou CHF. Dans les autres devises, le moyen de paiement est masqué sur la page de paiement.

Site public en HTTPS: pour les webhooks, votre site doit être accessible depuis Internet en HTTPS.

Clé de licence VibeFox: achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.

Installation

1. Dans WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier wcp_viva_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Viva Wallet > Manage, ou cliquez sur Settings sous le nom de l'extension sur la page Plugins.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

5. Saisissez les identifiants du compte de démo et/ou de production Viva, puis configurez la source de paiement et le webhook (voir Configuration).

6. Activez Enable/Disable. Effectuez un paiement de démo avec une carte de démo Viva pendant que Test Mode est actif, puis décochez Test Mode pour passer en production.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Viva Wallet. Au-dessus des champs, la page vous avertit lorsque le mode actuel n'a pas de Client ID, de Client Secret ou de Source Code (Viva Wallet is hidden at checkout until the Demo Client ID, Client Secret and Source Code are entered., ou Live en mode production) et lorsque la devise de la boutique n'est pas prise en charge. Lorsque le mode test est actif, elle affiche Test mode is on: payments go to the Viva demo environment. Dans la liste des moyens de paiement, Viva Wallet est indiqué comme nécessitant une configuration tant que le mode actuel n'a pas ces trois valeurs.

General

Enable/Disable: Enable Viva Wallet payment gateway active ou désactive le moyen de paiement. Par défaut : désactivé.

Title: le nom du moyen de paiement affiché aux clients sur la page de paiement. Par défaut : Viva Wallet.

Description: le texte affiché sous le moyen de paiement sur la page de paiement. Par défaut : Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.

Test Mode: Use the Viva demo environment (demo.vivapayments.com). Les nouveaux paiements et appels API utilisent les identifiants du compte de démo. Aucun argent réel n'est débité, et sur la page de paiement la description se termine par (Test mode: use Viva demo cards, no real money is charged.) Par défaut : activé. Décochez pour encaisser de vrais paiements avec le compte de production. Les paiements déjà effectués continuent d'être vérifiés et remboursés dans l'environnement où ils ont été faits.

Compte de démo (mode test) et compte de production

Les deux sections ont les mêmes champs : un jeu pour le compte de démo, un autre pour le compte de production. Dans votre compte Viva, ouvrez Settings > API Access et copiez les identifiants Smart Checkout (Client ID, Client Secret), le Merchant ID et l'API Key. Le Source Code se trouve dans Sales > Online payments > Websites / apps.

Client ID (Demo) / Client ID (Live): le Client ID OAuth 2.0 Smart Checkout du compte. Obligatoire.

Client Secret (Demo) / Client Secret (Live): le Client Secret OAuth 2.0 Smart Checkout du compte. Obligatoire.

Source Code (Demo) / Source Code (Live): le code à 4 chiffres de la source de paiement du compte. Ses Success URL et Failure URL doivent pointer vers cette boutique (voir ci-dessous). Obligatoire.

Merchant ID (Demo) / Merchant ID (Live): facultatif. Sert uniquement à répondre à la vérification de l'URL du webhook par Viva.

API Key (Demo) / API Key (Live): facultatif. Sert uniquement à répondre à la vérification de l'URL du webhook par Viva.

URL de retour et webhook

Payment source: dans Sales > Online payments > Websites / apps, créez une source de paiement pour le domaine de votre boutique, dans chaque compte que vous utilisez. Comme Success URL et Failure URL, saisissez les chemins situés après le domaine des deux adresses affichées dans les réglages, qui ressemblent à https://your-site/wc-api/viva_payment_success/ et https://your-site/wc-api/viva_payment_fail/.

Webhook: dans Settings > API Access > Webhooks, ajoutez l'URL affichée dans les réglages, qui ressemble à https://your-site/wp-json/wc-viva-gateway/v1/webhook, pour ces événements :

Viva vérifie l'URL avant de l'enregistrer. L'extension répond avec la clé de vérification de votre compte : elle récupère la clé avec le Merchant ID et l'API Key du mode actuel, ou utilise la clé saisie ci-dessous. Les webhooks confirment les paiements même lorsque le client ferme son navigateur. Les webhooks Viva ne sont pas signés, donc l'extension ne se fie jamais au webhook seul : chaque paiement est vérifié via l'API Viva avant que la commande soit marquée comme payée. Sans webhook, une commande n'est confirmée que lorsque le client revient sur la boutique après avoir payé.

Webhook Verification Key: facultatif. Laissez vide pour récupérer la clé automatiquement avec le Merchant ID et l'API Key du mode actuel, ou collez ici la clé de vérification de votre compte Viva.

Réglages avancés

Order Status After Payment: le statut de commande défini après un paiement réussi. Le statut est appliqué immédiatement, sans second changement de statut.

Brand Color: un code couleur HEX à 6 chiffres pour la page de paiement Viva, par exemple 0000ff. Un # en début est supprimé. Laissez vide pour la couleur par défaut. Toute autre valeur est refusée à l'enregistrement et la valeur précédente est conservée.

Debug Logging: Enable logging écrit les requêtes API dans WooCommerce > Status > Logs, source wcp_viva_gateway. Les clés et les données clients ne sont pas journalisées. Les erreurs sont toujours journalisées, même lorsque cette option est désactivée. Par défaut : désactivé.

Delete Data on Uninstall: Remove all plugin data when the plugin is deleted. Lorsqu'elle est active, la suppression de l'extension efface les réglages, la table des tentatives de paiement et les journaux de l'extension. Les notes et données des commandes sont conservées. Par défaut : désactivé.

Paiement

Le client choisit le moyen de paiement (par défaut Viva Wallet) et passe la commande. L'extension crée une commande de paiement Viva pour le total de la commande, dans la devise de la commande, puis envoie le client sur la page Viva Smart Checkout. Il y paie avec l'un des moyens activés dans votre compte Viva, comme les cartes, Apple Pay ou Google Pay. L'e-mail, le nom, le téléphone et le pays du client sont transmis à Viva, et la page s'ouvre dans la langue de votre site si Viva la prend en charge, sinon en anglais. Le paiement apparaît dans Viva sous le libellé WooCommerce # suivi du numéro de commande. La commande de paiement Viva expire au bout de 30 minutes.

Après le paiement, le client revient sur la page « Commande reçue » de votre boutique. La commande n'est marquée comme payée qu'après confirmation de Viva : l'extension relit la transaction via l'API Viva, au retour du client et sur le webhook. Si le paiement n'est pas encore confirmé, la page affiche We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed.

Si le paiement échoue ou si le client annule sur la page Viva, le statut de la commande ne change pas. Le client est renvoyé sur la page Pay for order avec The Viva Wallet payment was not completed. Please try again or choose another payment method. ou The Viva Wallet payment was cancelled. You can try again or choose another payment method., et peut payer à nouveau.

Si Viva ne peut pas démarrer le paiement, le client voit Viva Wallet payments are not available at the moment. Please choose another payment method or contact us. (identifiants absents ou incorrects) ou We could not connect to Viva Wallet. Please try again in a moment or choose another payment method. La raison technique est écrite dans le journal.

Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order, où la devise de cette commande est vérifiée. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).

L'extension ne prend que les paiements uniques, débités immédiatement sur la page Viva. Elle ne gère ni préautorisation et capture, ni paiements échelonnés, ni cartes enregistrées, ni WooCommerce Subscriptions, ni Viva Native Checkout (champs de carte sur votre propre page), ni terminaux POS. Lorsque le client lance une nouvelle tentative, l'ancienne commande de paiement Viva non payée n'est pas annulée ; Viva l'expire au bout de 30 minutes.

Commandes et remboursements

Order statuses

Pending payment: le client a été envoyé vers Viva et n'a pas encore payé, le paiement n'a pas encore été confirmé, ou le paiement a échoué ou a été annulé. Une note indique la commande de paiement Viva et l'environnement (démo ou production). Les tentatives échouées et annulées sont ajoutées aux notes de commande, et le client peut payer à nouveau.

Processing, Completed or On Hold: le paiement a été confirmé. Le statut suit Order Status After Payment. La note de commande indique le montant, l'ID de transaction Viva, l'environnement et le mode de confirmation (webhook ou retour du client).

On hold for review: Viva a signalé un montant ou une devise différents du total de la commande, par exemple lorsque la commande a été modifiée après que le client a commencé à payer. La note Viva Wallet payment held for review indique la raison. Comparez le paiement dans le tableau de bord Viva avec la commande, puis validez-le ou remboursez-le manuellement.

Un paiement reçu pour une commande annulée ou remboursée ne modifie pas le statut de la commande ; une note vous demande de rétablir la commande ou de rembourser le paiement dans le tableau de bord Viva. Si un second paiement arrive pour une commande déjà payée, la commande n'est pas modifiée à nouveau ; une note vous demande de rembourser le doublon dans le tableau de bord Viva.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Viva Wallet. Les remboursements totaux et partiels sont pris en charge pour les commandes ayant une transaction Viva confirmée. Le remboursement est envoyé au compte sur lequel le paiement a été effectué (démo ou production), dans la devise du paiement ; il faut donc que le Client ID et le Client Secret de ce compte soient saisis. Si Viva refuse le remboursement, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté aux notes de commande avec la transaction de remboursement Viva.

Les remboursements effectués dans le tableau de bord Viva ne sont pas importés. Si nécessaire, créez un remboursement manuel dans WooCommerce sans Refund via Viva Wallet.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > Viva Wallet. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, ainsi que votre domaine. Utilisez Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.

Une clé fonctionne sur un seul domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, Viva Wallet n'est pas affiché aux clients sur la page de paiement. Si un paiement est lancé malgré tout, le client voit This payment method is not available. Please choose another one. Les gestionnaires de la boutique connectés voient toujours le moyen de paiement, marqué (unlicensed — visible to admins only), afin de pouvoir configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page Plugins et sur les pages WooCommerce. Les commandes existantes ne sont pas touchées : les paiements déjà lancés sont toujours confirmés et les remboursements fonctionnent.

Lorsqu'une licence expire, l'extension continue de fonctionner, mais les mises à jour et l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Viva Wallet n'apparaît pas sur la page de paiement : vérifiez que la licence est active, que l'option Enable/Disable est activée et que le mode actuel dispose de son Client ID, de son Client Secret et de son Source Code (les champs Demo en mode test, les champs Live en mode production). La devise de la boutique (sur la page Pay for order, la devise de la commande) doit être l'une de EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK ou CHF. La page des réglages affiche un avertissement lorsqu'un élément manque.

Le paiement a été effectué, mais la commande reste en Pending payment: le webhook ne fonctionne pas. Dans Viva, vérifiez que le webhook existe dans le compte utilisé (démo ou production), que son URL est exactement celle affichée dans les réglages et que Transaction Payment Created est sélectionné. Vérifiez que le Client ID et le Client Secret du compte de ce paiement sont toujours saisis : l'extension en a besoin pour vérifier le paiement. Les détails figurent dans WooCommerce > Status > Logs, source wcp_viva_gateway.

Viva ne peut pas vérifier l'URL du webhook : saisissez le Merchant ID et l'API Key du mode actuel (ou la clé de vérification elle-même dans Webhook Verification Key), enregistrez, puis vérifiez à nouveau dans Viva. Pour vérifier le webhook de l'autre compte, basculez d'abord Test Mode ou saisissez la clé de ce compte.

Le webhook répond par une erreur : Viva affiche la réponse de votre boutique et réessaie les webhooks en échec. verification_failed (HTTP 500) signifie que l'API Viva n'a pas pu être jointe pour vérifier le paiement. busy (HTTP 503) signifie que la commande était en cours de traitement par une autre requête au même moment. transaction_not_found (HTTP 404) signifie que la transaction n'existe pas dans le compte de ce paiement, par exemple à cause d'identifiants incorrects. Les événements concernant les paiements d'autres boutiques du même compte Viva reçoivent la réponse ignored.

Le client voit une erreur lors de la commande : activez Debug Logging et consultez WooCommerce > Status > Logs, source wcp_viva_gateway. Un Client ID ou un Client Secret incorrect, ou un Source Code manquant, affiche le message indiquant que les paiements Viva Wallet ne sont pas disponibles. Si Viva ne peut pas être joint ou refuse la commande de paiement, par exemple parce que le Source Code appartient à un autre compte, le client reçoit le message indiquant que la boutique n'a pas pu se connecter à Viva Wallet.

La commande est On hold après le paiement : lisez la note de commande. Le montant ou la devise payés ne correspondaient pas à la commande. Finalisez la commande ou remboursez le paiement.

Le remboursement échoue avec This payment was made in the Viva demo (or live) environment: le Client ID et le Client Secret du compte sur lequel le paiement a été effectué ne sont pas saisis. Saisissez-les et réessayez. Les autres erreurs de remboursement affichent le code HTTP et le message de Viva.

Le bloc de licence affiche une erreur : suivez le message affiché dans le bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner avec le dernier statut connu.

Pour les développeurs : le filtre viva_wp_supported_currencies active d'autres devises prises en charge par votre compte Viva, viva_wp_create_order_payload modifie la requête de commande de paiement (le montant, la devise et le Source Code doivent rester identiques) et viva_wp_icon modifie l'icône sur la page de paiement.

Désinstallation

Désactiver l'extension conserve toutes les données ; seuls les jetons d'accès Viva en cache sont supprimés. Pour la retirer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension, ainsi que les jetons en cache et les clés de webhook, sont toujours supprimés. Les réglages, la table des tentatives de paiement et les journaux de l'extension (fichiers journaux, y compris ceux qui ont été archivés, et entrées de base de données) ne sont supprimés que si Delete Data on Uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Viva Wallet est une marque déposée de son propriétaire respectif. Cette extension n'est ni affiliée à Viva Wallet, ni approuvée par Viva Wallet.