VibeFox Viva Wallet for PrestaShop — Aide
Prérequis
PrestaShop : 8.0 à 9.x.
PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les anciennes versions de PHP.
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 : EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK ou CHF. Pour les autres devises, le moyen de paiement est masqué à l'étape de paiement.
Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un seul domaine.
Installation
1. Dans le back-office, allez dans Modules > Module Manager et cliquez sur Upload a module. Choisissez le fichier ZIP du module.
2. Une fois le téléversement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Viva Wallet Gateway dans la liste des modules et cliquez sur Configure.
3. Saisissez votre clé de licence VibeFox dans le champ License key du bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).
4. Saisissez les identifiants du compte de démo et/ou de production Viva, puis configurez la source de paiement et le webhook dans votre compte Viva (voir Configuration).
5. Activez Enable/Disable et cliquez sur Save. Effectuez un paiement de démo avec une carte de démo Viva pendant que Test Mode est activé, puis désactivez Test Mode pour passer en production.
À l'installation, le module crée le statut de commande Viva Wallet payment on hold. Le module est proposé pour les pays actifs au moment de l'installation. Vous pouvez modifier les devises, les pays et les groupes de clients dans Payment > Preferences ; vous pourrez y ajouter de nouveaux pays plus tard.
Configuration
Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Viva Wallet Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. 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 par défaut de la boutique n'est pas prise en charge. Tant que le mode test est activé, elle affiche Test mode is on: payments go to the Viva demo environment. Enregistrer les réglages supprime les jetons d'accès Viva en cache, afin que les nouveaux identifiants soient utilisés immédiatement.
Viva Wallet
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 que voient les clients lors du paiement. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Viva Wallet. Obligatoire : un titre vide n'est pas enregistré et la page affiche Enter a title for the payment method.
Description : le texte affiché sous le moyen de paiement lors du paiement. Par défaut : Pay securely with Viva Wallet — cards, Apple Pay, Google Pay and more.
Test Mode : utilise l'environnement de démo Viva (demo.vivapayments.com). Les nouveaux paiements et les appels API utilisent les identifiants du compte de démo. Aucun argent réel n'est débité, et lors du paiement les clients voient (Test mode: use Viva demo cards, no real money is charged.) Par défaut : activé. Désactivez-le 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 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 de Smart Checkout du compte. Obligatoire pour les paiements.
Client Secret (Demo) / Client Secret (Live) : le Client Secret OAuth 2.0 de Smart Checkout du compte. Obligatoire pour les paiements.
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 pour les paiements.
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.
Les Client Secret et API Key enregistrés ne sont jamais réaffichés. Le champ reste vide et affiche Saved — leave empty to keep it. Ne saisissez une nouvelle valeur que pour la modifier.
Clear saved secrets : cochez un secret et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.
URL de retour et webhook
Addresses for the Viva account : ce champ affiche les trois adresses de votre boutique à saisir dans le compte Viva. Avec des URL conviviales, elles ressemblent à https://your-shop/module/wcp_viva_gateway/success, https://your-shop/module/wcp_viva_gateway/fail et https://your-shop/module/wcp_viva_gateway/webhook, éventuellement avec un code de langue comme /en/. Copiez-les exactement telles que les réglages les affichent.
Payment source : dans Sales > Online payments > Websites / apps, créez une source de paiement pour le domaine de votre boutique, dans chacun des comptes utilisés. Comme Success URL et Failure URL, saisissez la partie des adresses de succès et d'échec qui suit le domaine.
Webhook : dans Settings > API Access > Webhooks, ajoutez l'adresse du webhook pour les événements suivants :
Viva vérifie l'URL avant de l'enregistrer. Le module répond avec la clé de vérification de votre compte : il la récupère 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 le navigateur. Les webhooks Viva ne sont pas signés, donc le module ne fait jamais confiance au webhook seul : chaque paiement est vérifié via l'API Viva avant la création de la commande. Sans webhook, une commande n'est créée que lorsque le client revient sur la boutique après avoir payé.
Webhook Verification Key : facultatif. Laissez-le 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 attribué 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 # au début est supprimé. Laissez vide pour la couleur par défaut. Toute autre valeur n'est pas enregistrée : la page affiche Brand Color must be a 6-digit HEX code (e.g. 0000ff). The previous value was kept.
Debug Logging : écrit les requêtes API dans logs/viva_wp_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les clés, jetons et données clients ne sont pas journalisés. Les erreurs sont toujours journalisées, même lorsque l'option est désactivée. Par défaut : désactivé.
Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.
Delete Data on Uninstall : lorsqu'elle est activée, la désinstallation du module supprime les réglages et les journaux du module. Les commandes et leurs données de paiement (tentatives de paiement Viva, remboursements, statut de commande) ne sont jamais supprimées. Par défaut : désactivé.
Processus de commande
À l'étape de paiement, le client choisit le moyen de paiement (par défaut Viva Wallet) et voit la note You will be redirected to the secure Viva Wallet payment page (cards, Apple Pay, Google Pay and more). Après confirmation, le module crée une commande de paiement Viva pour le total du panier, dans la devise du panier, et envoie le client sur la page Viva Smart Checkout. Il y paie avec l'un des moyens activés dans votre compte Viva. 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 du panier si Viva la prend en charge. Dans Viva, le paiement apparaît comme Cart #, suivi du numéro de panier et du nom de votre boutique. La commande de paiement Viva expire au bout de 30 minutes. À ce stade, aucune commande n'existe encore.
Après le paiement, le client revient sur votre boutique. La commande n'est marquée comme payée qu'après confirmation de Viva : le module relit la transaction via l'API Viva, au retour du client et sur le webhook. La commande est alors créée et le client voit la page standard de confirmation de commande. Si le paiement n'est pas encore confirmé, une page Payment confirmation affiche We are waiting for Viva Wallet to confirm your payment. You will receive an e-mail as soon as it is confirmed. avec les boutons Check again et Back to checkout ; le webhook crée la commande dès que Viva confirme le paiement.
Si le paiement échoue ou si le client annule sur la page Viva, aucune commande n'est créée et le panier est conservé. Le client revient à l'étape de paiement 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 reste à l'étape de paiement avec 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.
Les pages de retour n'affichent la confirmation de commande qu'au client qui a payé. Toute autre personne qui ouvre l'adresse de retour est redirigée vers l'historique des commandes ou vers l'étape de paiement, sans détails de commande.
Le webhook fonctionne lorsque la boutique est en mode maintenance et n'est pas bloqué par la restriction de pays de votre boutique.
Le module ne prend que les paiements uniques, débités immédiatement sur la page Viva. Il ne gère ni pré-autorisation et capture, ni paiements échelonnés, ni cartes enregistrées, ni abonnements, ni Viva Native Checkout (champs de carte sur votre propre page), ni terminaux de point de vente (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
Statuts de commande
Pas encore de commande : le client a été envoyé vers Viva et n'a pas payé, le paiement a échoué ou a été annulé, ou Viva n'a pas encore finalisé le paiement. Seul le panier existe, et le client peut payer à nouveau.
Payment accepted, Delivered ou Viva Wallet payment on hold : le paiement a été confirmé. Le statut suit Order Status After Payment. Le paiement est enregistré avec l'identifiant de transaction Viva, et une note indique le montant, la transaction, le code de commande Viva, l'environnement (démo ou production) et le mode de confirmation (webhook ou retour du client).
Viva Wallet payment on hold après un écart : Viva a signalé un montant ou une devise différent du total du panier, par exemple parce que le panier a été modifié après le début du paiement. La commande est créée sans paiement enregistré, et la note Viva Wallet payment held for review indique la raison. Le client voit la page standard de confirmation de commande, sans promesse de confirmation Viva. Comparez le paiement dans le tableau de bord Viva avec la commande, puis traitez-la ou remboursez-la manuellement. Si un paiement correspondant au même panier arrive plus tard, la commande passe au statut payé.
Un paiement reçu pour une commande annulée ou remboursée ne modifie pas le statut de la commande ; une note vous invite à rétablir la commande ou à 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 ; une note vous invite à rembourser le doublon dans le tableau de bord Viva.
Bloc Viva Wallet payment
La page de commande affiche un bloc Viva Wallet payment avec le code de commande Viva, l'identifiant de transaction, l'environnement et le Source Code, le statut Viva, les montants payés et remboursés, un badge Demo pour les paiements de démo, l'historique des remboursements, les tentatives de paiement du panier (s'il y en a eu plusieurs) et les Viva Wallet notes de la commande.
Remboursements
Dans le bloc Viva Wallet payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Viva Wallet. Confirmez la question Refund this amount via Viva Wallet? This cannot be undone. Les remboursements totaux et partiels sont pris en charge pour les commandes dont la transaction Viva est confirmée. Vous devez avoir le droit de modifier les commandes ; l'accès aux modules n'est pas nécessaire. Vous pouvez rembourser jusqu'au montant débité par Viva pour le paiement, même si la commande a été modifiée ensuite. 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, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec la transaction de remboursement Viva. Un remboursement total passe la commande au statut Refunded. Un remboursement partiel ne modifie pas le statut. Une commande mise en attente de vérification sans paiement confirmé ne peut pas être remboursée depuis le bloc.
Le module ne crée pas d'avoirs. Les boutons de remboursement standard de PrestaShop sur la page de commande ne renvoient pas d'argent via Viva. Les remboursements effectués dans le tableau de bord Viva ne sont pas importés. Mettez la commande à jour manuellement si nécessaire.
Clé de licence
Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Viva Wallet Gateway est le premier bloc de Modules > Module Manager > VibeFox Viva Wallet Gateway > Configure, au-dessus des réglages. Saisissez la clé dans License key et cliquez sur Activate. Ensuite, le bloc affiche la clé masquée, le statut (par exemple la date jusqu'à laquelle la licence est active et votre domaine) et les boutons Check now pour vérifier à nouveau le statut, Change key pour saisir une autre clé et Remove key pour retirer la clé de cette boutique. En dessous figurent la ligne Product: presta-payment-viva et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de l'autorisation Configure pour le module peuvent modifier la clé. Les textes du bloc suivent la langue du back-office (l'anglais et le russe sont inclus).
Si la clé n'est pas acceptée, le bloc indique la raison, par exemple Key not found, This key belongs to another product, Domain limit reached ou License expired on suivi d'une date. Après un changement d'adresse de la boutique, ou après avoir libéré un emplacement de domaine dans votre compte, cliquez sur Check now. Si le serveur de licences est injoignable, le module continue de fonctionner avec le dernier statut connu.
Une clé fonctionne sur un seul domaine : le domaine de la boutique principale, y compris dans une configuration multiboutique. Retirer la clé de la boutique ne libère pas son emplacement de domaine. Libérez l'emplacement dans votre compte vibefox.net.
Sans clé active, Viva Wallet n'est pas affiché aux clients lors du paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. La vitrine PrestaShop ne sait pas que vous êtes connecté au back-office : le moyen de paiement est donc masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais ne pas le tester à l'étape de paiement. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés par le webhook Viva et le retour vers la boutique, et les remboursements fonctionnent.
Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et le support nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement pendant votre travail dans le back-office : une fois par jour pendant les 14 premiers jours après la saisie de la clé, puis une fois par semaine. Aucune tâche cron n'est nécessaire. La désinstallation ou la réinitialisation du module supprime toujours la clé de licence et le statut de licence.
Dépannage
Viva Wallet n'apparaît pas à l'étape de paiement : vérifiez que la licence est active, que Enable/Disable est activé 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 du panier doit être l'une de EUR, GBP, PLN, RON, BGN, CZK, HUF, DKK, SEK, NOK ou CHF. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe de clients. La page des réglages affiche un avertissement lorsque des identifiants manquent.
Le paiement a abouti, mais aucune commande n'a été créée : 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 : le module en a besoin pour vérifier le paiement. Activez Debug Logging et consultez le champ Log. La commande est aussi créée lorsque le client revient sur la boutique après avoir payé.
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 relancez la vérification dans Viva. Pour vérifier le webhook de l'autre compte, changez 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 renouvelle les webhooks en échec. verification_failed (HTTP 500) signifie que l'API Viva n'a pas pu être jointe pour vérifier le paiement, ou que la commande n'a pas pu être créée (par exemple parce que le module est désactivé). busy (HTTP 503) signifie que la commande était traitée 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 erronés. 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 en choisissant Viva Wallet : consultez le champ Log sur la page du module. Un Client ID ou un Client Secret incorrect affiche le message indiquant que les paiements Viva Wallet ne sont pas disponibles. Si Viva est injoignable 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.
Le client revient et voit We could not find your order. If you were charged, please contact us.: le code de commande Viva dans l'adresse de retour ne correspond pas à un paiement de cette boutique, par exemple parce que la source de paiement d'une autre boutique pointe ici. Vérifiez les Success URL et Failure URL de la source de paiement.
La commande passe en Viva Wallet payment on hold après le paiement : lisez les notes du bloc Viva Wallet payment (voir Statuts de commande), puis traitez 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 où 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 affiche Transaction ID not found. Cannot process refund.: la commande n'a pas de paiement Viva confirmé, par exemple après un écart de montant. Remboursez le paiement dans le tableau de bord Viva si nécessaire.
Désinstallation
Désactiver le module conserve toutes les données ; seuls les jetons d'accès Viva en cache sont supprimés. Pour le supprimer, allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Viva Wallet Gateway et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Les jetons d'accès en cache et les clés de webhook sont toujours supprimés. Si Delete Data on Uninstall est activé, les réglages et le journal sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une future réinstallation. Les tentatives de paiement et les remboursements Viva ainsi que le statut de commande Viva Wallet payment on hold sont toujours conservés, de sorte que les commandes payées auparavant peuvent encore être remboursées après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.
Viva Wallet est une marque de son propriétaire respectif. Ce module n'est ni affilié à Viva Wallet ni approuvé par Viva Wallet.