VibeFox Yoco 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.

Devise de la boutique : rand sud-africain (ZAR). Yoco n'accepte que le ZAR. Dans toute autre devise, le mode de paiement n'est pas proposé au checkout. Le total de la commande doit être d'au moins R2,00.

Compte Yoco : un compte Yoco avec paiements en ligne. Vous avez besoin de ses clés secrètes, que vous trouvez dans le Yoco Business Portal sous Selling Online > Payment Gateway. Seules les clés secrètes sont saisies. Le webhook est enregistré par le module, et son secret de signature est renseigné à votre place.

Site public : Yoco envoie des webhooks à votre boutique, elle doit donc être accessible depuis Internet. L'URL du webhook doit accepter un POST sans redirection.

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 Yoco Pay Gateway dans la liste des modules et cliquez sur Configure.

3. Saisissez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page Configure, puis cliquez sur Activate (voir Clé de licence).

4. Collez la clé secrète de test (sk_test_...) et, lorsque vous êtes prêt, la clé secrète réelle (sk_live_...). Cliquez sur Save. Le webhook est enregistré pour chaque mode qui a une clé.

5. Activez Enable/Disable et cliquez sur Save. Effectuez un paiement de test avec une carte de test Yoco pendant que Test mode est activé, puis désactivez Test mode pour encaisser de vrais paiements.

À l'installation, le module crée le statut de commande Yoco payment on hold. PrestaShop active le nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les limiter dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Yoco Pay Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit lorsque la devise de la boutique n'est pas le ZAR (Yoco n'est alors pas proposé au checkout) et lorsque le mode actuel n'a pas de clé secrète, par exemple Enter the test secret key to offer Yoco at checkout (test mode). À l'enregistrement, le module vérifie les clés et les secrets de webhook, et enregistre les webhooks. Les messages à ce sujet apparaissent en haut de la page.

Yoco

Enable/Disable : Enable Yoco active ou désactive le mode de paiement. Par défaut : désactivé.

Title : le nom du mode de paiement que voient les clients au checkout. C'est aussi le nom enregistré dans la commande. Par défaut : Card or Instant EFT (Yoco).

Description : le texte affiché sous le mode de paiement au checkout. Par défaut : You will be redirected to the secure Yoco page to pay by card or Instant EFT.

Clés API

Copiez les clés secrètes depuis le Yoco Business Portal sous Selling Online > Payment Gateway. Yoco dispose d'une seule API pour les deux modes : c'est la clé qui détermine si un paiement est un test ou un vrai paiement. Le mode test n'utilise que la clé de test, le mode réel uniquement la clé réelle.

Test mode : utilise la clé secrète de test. Aucun argent réel n'est débité ; payez avec les cartes de test Yoco. Par défaut : activé. Désactivez-le pour encaisser de vrais paiements. Tant qu'il est activé, les clients voient Test mode — use a Yoco test card; no real money is charged. sous le mode de paiement.

Test secret key : la clé secrète du mode test. Elle commence par sk_test_.

Live secret key : la clé secrète du mode réel. Elle commence par sk_live_.

Une clé qui ne commence pas par le préfixe attendu n'est pas enregistrée : la page affiche une erreur, par exemple Yoco: the test secret key must start with sk_test_ — the previous value was kept. Si Yoco signale pendant l'enregistrement du webhook qu'une clé appartient à l'autre mode, la page vous en informe.

Les clés et secrets enregistrés ne sont jamais réaffichés. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier.

Webhooks

Yoco confirme les paiements et les remboursements à l'URL affichée dans Webhook URL de cette section. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_yoco_pay/webhook, éventuellement avec un code de langue comme /en/. Vous n'avez pas besoin de créer le webhook dans le portail Yoco. Lorsque vous enregistrez les réglages, le module enregistre l'URL auprès de Yoco pour chaque mode qui a une clé secrète mais pas de secret de webhook, et stocke le secret de signature dans le champ de ce mode. Il réenregistre l'URL lorsque la clé secrète de ce mode ou l'URL du webhook change. Quand l'URL change, l'ancien enregistrement est supprimé.

Pour chaque mode (Test et Live), la section affiche l'état du webhook :

Le module gère ces événements (ils sont également listés dans cette section) :

Les webhooks sans signature valide sont rejetés. Un événement doit être signé avec le secret du mode dans lequel le paiement a été effectué ; ainsi, une clé secrète de test ne confirme jamais un paiement réel. Copiez l'URL exactement comme les réglages l'affichent, car le webhook doit atteindre votre boutique sans redirection.

Test webhook secret : renseigné automatiquement lors de l'enregistrement du webhook. Collez un secret (whsec_...) uniquement si vous avez enregistré vous-même l'URL du webhook.

Live webhook secret : renseigné automatiquement lors de l'enregistrement du webhook. Videz-le et enregistrez pour enregistrer à nouveau le webhook.

Un secret de webhook doit ressembler à whsec_ suivi d'un texte en base64. Toute autre valeur n'est pas enregistrée, et la valeur précédente est conservée.

Clear saved secrets : cochez une clé ou un secret et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée. Vider un secret de webhook puis enregistrer réenregistre le webhook.

Avancé

Debug log : écrit les requêtes et les webhooks Yoco dans logs/yoco_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements, comme les requêtes échouées vers Yoco et les webhooks rejetés, sont toujours journalisés. Les clés, les secrets de webhook et les adresses e-mail sont masqués. 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 : lorsque l'option est activée, la désinstallation du module supprime les réglages, le journal et les webhooks que le module a enregistrés chez Yoco. Les données de commande (identifiants de checkout et de paiement Yoco, remboursements) et le statut de commande Yoco payment on hold sont toujours conservés, car ils sont nécessaires aux remboursements. Par défaut : désactivé.

Checkout

À l'étape de paiement, le client choisit le mode de paiement (par défaut Card or Instant EFT (Yoco)) et confirme. Le module crée un checkout Yoco pour le total du panier en centimes et envoie le client sur la page de paiement Yoco, où il paie par carte ou Instant EFT. Aucune commande n'existe encore à ce stade.

Après le paiement, le client revient sur votre boutique. La commande n'est marquée payée qu'après confirmation de Yoco : le module demande le checkout à Yoco lorsque le client revient, puis à nouveau lorsque le webhook signé arrive. La commande est alors créée et le client voit la page standard de confirmation de commande avec Your payment with Yoco has been received. Si Yoco n'a pas encore confirmé le paiement au retour du client, une page Payment confirmation affiche We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again. avec un bouton Check again ; le webhook crée la commande dès son arrivée.

Si le client annule sur la page Yoco, il revient au checkout avec The Yoco payment was cancelled. Your cart is saved — you can pay again or choose another payment method. Si le paiement échoue, le message est The Yoco payment was not successful. Please try again or choose another payment method. Le panier est conservé.

Avant une nouvelle tentative de paiement pour le même panier, le module vérifie la précédente auprès de Yoco. Si elle a déjà été payée, la commande est créée sans nouvelle page de paiement. Si elle est toujours ouverte pour le même montant et a été créée il y a moins de 30 minutes, le client obtient de nouveau la même page Yoco. Sinon, un nouveau checkout Yoco est créé.

Si Yoco ne peut pas démarrer le paiement, le client reste au checkout avec Yoco could not start the payment. Please try again in a moment or choose another payment method. et la raison est écrite dans le journal. Une commande inférieure à R2,00 affiche Yoco requires an order total of at least R2.00.

Le webhook fonctionne pendant que la boutique est en mode maintenance et n'est pas bloqué par la restriction géographique de votre boutique.

Les paiements sont débités immédiatement sur la page Yoco. Le module ne gère ni cartes enregistrées, ni abonnements ou paiements récurrents, ni formulaire de carte sur le site, ni autorisation et capture séparées, et il ne fonctionne pas dans des devises autres que le ZAR.

Commandes et remboursements

Statuts de commande

No order yet : le client a été envoyé vers Yoco et n'a pas payé, a annulé sur la page Yoco, ou Yoco n'a pas encore confirmé le paiement. Seul le panier existe.

Payment accepted : le paiement a été confirmé. Il est enregistré avec l'identifiant de paiement Yoco comme identifiant de transaction, et une note indique le montant, les identifiants de paiement et de checkout Yoco, le mode et la manière dont le paiement a été confirmé (retour du client, webhook ou vérification avant une nouvelle tentative de paiement).

Yoco payment on hold : Yoco a signalé un montant ou une devise différents du total du panier, par exemple parce que le panier a été modifié dans un autre onglet après le début du paiement. Aucun paiement n'est enregistré, la note l'explique et le client voit We received your payment and are reviewing it. We will contact you if anything else is needed. Vérifiez le paiement avant l'expédition. Si le client paie ensuite le bon montant lors d'une autre tentative, la commande passe à Payment accepted.

Cancelled or Refunded : un paiement qui arrive pour une telle commande ne la modifie pas. Une note vous invite à rembourser le paiement dans le portail Yoco ou à rétablir la commande manuellement. Le client voit Your payment was received after the order had been cancelled. Please contact us — do not pay again.

Si un second paiement arrive pour une commande déjà payée, la commande n'est pas modifiée. Une note vous invite à le rembourser dans le portail Yoco.

Bloc de paiement Yoco

La page de commande affiche un bloc Yoco payment avec les identifiants de paiement et de checkout Yoco, le statut, le montant payé et remboursé, un badge Test mode pour les paiements de test, l'historique des remboursements, les tentatives de paiement du panier (lorsqu'il y en a plusieurs) et les Yoco notes de la commande.

Remboursements

Dans le bloc Yoco payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Yoco. Confirmez la question Refund this amount through Yoco? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez disposer du droit de modifier les commandes. Les remboursements sont calculés sur le montant encaissé par Yoco : vous ne pouvez rembourser au maximum que ce que le client a réellement payé, même si la commande a été modifiée par la suite. Le remboursement est envoyé dans le mode où le paiement a été effectué (test ou réel), la clé secrète de ce mode doit donc être renseignée. Un remboursement répété après une réponse perdue n'est pas versé deux fois.

Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec l'identifiant de remboursement Yoco. Un remboursement total place la commande en Refunded ; un remboursement partiel ne modifie pas le statut. Si Yoco refuse le remboursement, le bloc affiche Yoco refused the refund: avec le motif, et aucun remboursement n'est enregistré. Si Yoco signale le remboursement comme en attente, le bloc indique qu'il est toujours en attente. Ne le répétez pas : il sera enregistré lorsque Yoco le confirmera par webhook. Les remboursements sont disponibles pour les commandes payées par un checkout Yoco. Une commande en Yoco payment on hold n'a pas de checkout payé à rembourser ; remboursez-la dans le portail Yoco.

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 Yoco.

Les remboursements effectués dans le portail Yoco arrivent par le webhook refund.succeeded et sont enregistrés dans l'historique des remboursements et les notes. Lorsqu'ils atteignent le montant payé, la commande passe à Refunded. Un remboursement supérieur au montant restant à rembourser n'est pas enregistré, et une note vous demande de vérifier la commande. Un remboursement échoué ajoute une note indiquant que l'argent n'a pas été rendu au client.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Yoco Pay Gateway est le premier bloc de Modules > Module Manager > VibeFox Yoco Pay 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) ainsi que 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-yoco 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 : celui 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-le dans votre compte vibefox.net.

Sans clé active, Yoco n'est pas affiché aux clients au checkout. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. La boutique 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 pas le tester au checkout. Un rappel apparaît dans Modules > Module Manager, dans l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà commencés sont toujours confirmés, 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é 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

Yoco n'apparaît pas au checkout : vérifiez que la licence est active, que Enable/Disable est activé et que le mode actuel a une clé secrète : Test secret key en mode test, Live secret key en mode réel. La devise du panier doit être le ZAR, et le total de la commande d'au moins R2,00. La page des réglages affiche un avertissement lorsque la clé manque ou que la devise de la boutique n'est pas le ZAR. Dans Payment > Preferences, vérifiez que le module est autorisé pour le ZAR, le pays du client et le groupe du client.

Le paiement a abouti, mais aucune commande n'a été créée : le webhook ne fonctionne pas. Ouvrez la section Webhooks des réglages et vérifiez l'état du mode utilisé. S'il n'est pas enregistré, ou enregistré pour une autre URL, enregistrez les réglages. Si l'enregistrement échoue, la page indique la raison. Si vous avez saisi le secret vous-même, vérifiez qu'il appartient au webhook de cette URL et de ce mode. La commande est aussi créée lorsque le client revient sur la boutique après avoir payé, et lorsque le client tente de payer à nouveau.

Impossible d'enregistrer le webhook : les paiements sont toujours confirmés lorsque les clients reviennent sur la boutique. Corrigez la raison indiquée dans le message, par exemple la boutique doit être accessible depuis Internet en HTTPS, puis enregistrez à nouveau. Vous pouvez aussi enregistrer l'URL vous-même et coller le secret de signature.

Les webhooks sont rejetés : les webhooks rejetés sont écrits dans le journal. webhook secret not configured signifie qu'aucun secret de webhook n'est défini. invalid signature signifie que le secret appartient à un autre enregistrement ou à un autre mode. timestamp outside the tolerance signifie que l'horloge du serveur est erronée : les signatures ne sont acceptées que dans les 5 minutes qui suivent l'heure du serveur. checkout not completed yet — retry et could not confirm the checkout with Yoco — retry sont temporaires ; Yoco renvoie le webhook.

L'URL du webhook n'affiche que POST dans le navigateur : c'est normal. L'URL n'accepte que les requêtes de Yoco.

Erreur à l'enregistrement « The secret key must start with sk_test_ / sk_live_ » : une clé a été collée dans le mauvais champ. La clé de test commence par sk_test_, la clé réelle par sk_live_. La valeur précédente a été conservée.

Le client voit une erreur lorsqu'il choisit Yoco : consultez le champ Log sur la page du module. Yoco is not available at the moment. Please choose another payment method. signifie que le mode actuel n'a pas de clé secrète.

Le client est informé qu'un paiement doit être examiné : une tentative a été payée avec un montant différent, ou après l'annulation de la commande. Lisez les notes du bloc Yoco payment et honorez la commande ou remboursez le paiement dans le portail Yoco.

Le remboursement échoue avec un message concernant le mode : le paiement a été effectué en mode test ou réel, et la clé secrète de ce mode n'est pas renseignée. Saisissez-la et réessayez.

Le remboursement échoue avec No answer from Yoco : rien n'a été enregistré dans PrestaShop. Si Yoco a bien traité le remboursement, répétez le même remboursement : il ne sera pas remboursé deux fois.

Développeurs : le hook actionYocoPCheckoutPayload permet à un autre module de modifier la requête qui crée le checkout Yoco.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Yoco Pay Gateway et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete data est activé, les réglages, le journal et les webhooks que le module a enregistrés chez Yoco sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une réinstallation ultérieure. Les checkouts et remboursements Yoco et le statut de commande Yoco 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 identifiants de transaction.

Yoco est une marque de son propriétaire respectif. Ce module n'est ni affilié à Yoco ni approuvé par Yoco.