VibeFox Yoco for WooCommerce — Aide

Prérequis

WordPress : 6.2 ou ultérieur.

WooCommerce : 8.0 ou ultérieur, installé et activé. L'extension ne s'active pas sans lui.

PHP : 8.0 ou ultérieur.

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

Compte Yoco : un compte Yoco avec paiements en ligne. Il vous faut 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 l'extension, et son secret de signature est renseigné pour vous.

Site public : Yoco envoie des webhooks à votre site, il 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 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_yoco_pay dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Yoco > Manage.

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

5. Collez la clé secrète de test (sk_test_...) et, lorsque vous êtes prêt, la clé secrète réelle (sk_live_...). Enregistrez les réglages. Le webhook est enregistré pour chaque mode qui dispose d'une clé.

6. Activez Enable/Disable. Effectuez un paiement test avec une carte de test Yoco tant que Test mode est activé, puis décochez Test mode pour accepter de vrais paiements.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Yoco. 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é à la caisse) et lorsque le mode actuel n'a pas de clé secrète. Dans la liste des moyens de paiement, Yoco est signalé comme nécessitant une configuration tant que le mode actuel n'a pas de clé secrète. À l'enregistrement, l'extension vérifie les clés et les secrets des webhooks, et enregistre les webhooks. Les messages à ce sujet apparaissent en haut de la page.

Général

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

Title: le nom du moyen de paiement que voit le client à la caisse. Par défaut : Card or Instant EFT (Yoco).

Description: le texte affiché sous le moyen de paiement à la caisse. 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 : la clé 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: Use the test secret key (no real payments). Aucun argent réel n'est débité ; payez avec les cartes de test de Yoco. Par défaut : on. Décochez-la pour accepter de vrais paiements.

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 et conserve la valeur précédente. Si Yoco signale pendant l'enregistrement du webhook qu'une clé appartient à l'autre mode, la page vous l'indique.

Webhooks

Yoco confirme les paiements et les remboursements à l'URL du webhook affichée dans cette section. Elle ressemble à https://your-site/wc-api/yoco_pay_webhook/. Vous n'avez pas à créer le webhook dans le portail Yoco. À l'enregistrement des réglages, l'extension enregistre l'URL auprès de Yoco pour chaque mode qui dispose d'une clé secrète mais pas d'un secret de webhook, et stocke le secret de signature dans le champ de ce mode. Elle enregistre de nouveau l'URL lorsque la clé secrète de ce mode ou l'URL du webhook change. Lorsque l'URL change, l'ancien enregistrement est supprimé.

Pour chaque mode, la section affiche l'état du webhook :

L'extension gère ces événements :

Les webhooks sans signature valide sont rejetés. Si votre site utilise un préfixe de langue dans les URL, gardez l'URL exactement telle qu'affichée dans les réglages, 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 champ et enregistrez pour réenregistrer 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.

Avancé

Debug log: Log Yoco requests and webhooks écrit les requêtes et les webhooks dans WooCommerce > Status > Logs, source wcp_yoco_pay. 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 : off.

Delete data: Delete the settings and logs of this plugin when it is deleted. La désactivation ne supprime jamais rien. Les données de commande (identifiants du checkout et du paiement Yoco) sont toujours conservées, car elles sont nécessaires aux remboursements. Par défaut : off.

Paiement

Le client choisit le moyen de paiement (par défaut Card or Instant EFT (Yoco)) et passe commande. En mode test, la caisse affiche Test mode — use a Yoco test card; no real money is charged. L'extension crée un checkout Yoco pour le total de la commande en centimes et envoie le client sur la page de paiement Yoco, où il paie par carte ou Instant EFT.

Après le paiement, le client revient sur votre boutique. La commande n'est marquée payée qu'après confirmation par Yoco : l'extension demande à Yoco le checkout lorsque le client revient, puis de nouveau lorsque le webhook signé arrive. Si Yoco n'a pas encore confirmé le paiement, la page de confirmation de commande affiche We are waiting for Yoco to confirm your payment. The order will be updated automatically — please do not pay again.

Si le client annule sur la page Yoco, la commande reste non payée et le client arrive sur la page Pay for order avec le message The Yoco payment was cancelled. Your order is saved — you can pay again below 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. et une note est ajoutée à la commande.

Le client peut payer à nouveau une commande non payée depuis la page Pay for order. Avant une nouvelle tentative, l'extension vérifie la précédente auprès de Yoco. Si elle a déjà été payée, la commande est finalisé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 reçoit de nouveau la même page Yoco.

Si Yoco ne peut pas démarrer le paiement, le client voit Yoco could not start the payment. Please try again in a moment or choose another payment method. et la raison est ajoutée aux notes de commande. Une commande inférieure à R2,00 affiche Yoco requires an order total of at least R2.00.

Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).

Les paiements sont débités immédiatement sur la page Yoco. L'extension 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 elle ne fonctionne pas dans d'autres devises que le ZAR.

Commandes et remboursements

Statuts de commande

Pending payment: le client a été envoyé vers Yoco et n'a pas encore payé, a annulé sur la page Yoco, ou Yoco n'a pas encore confirmé le paiement.

Processing or Completed: le paiement a été confirmé. WooCommerce passe la commande en « En cours », ou en « Terminée » pour les commandes ne comportant que des produits virtuels téléchargeables. La note de commande indique le montant, les identifiants du paiement et du 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). L'identifiant de transaction est l'identifiant de paiement Yoco.

On hold: Yoco a signalé un montant ou une devise différents du total de la commande, par exemple parce que la commande a été modifiée après le début du paiement. La note l'explique, et le client qui revient de Yoco 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.

Cancelled or Refunded: un paiement reçu 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 qui revient de Yoco 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 à nouveau. Une note vous invite à le rembourser dans le portail Yoco.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur le bouton Refund via suivi du nom de votre moyen de paiement (par défaut Card or Instant EFT (Yoco)). Les remboursements totaux et partiels sont pris en charge. Le remboursement est envoyé dans le mode dans lequel le paiement a été effectué (test ou réel), la clé secrète de ce mode doit donc être renseignée. Un remboursement relancé après une réponse perdue n'est pas versé deux fois.

Un remboursement réussi est ajouté aux notes de commande avec l'identifiant de remboursement Yoco. Si Yoco refuse le remboursement, WooCommerce affiche Yoco refused the refund: avec la raison, et aucun remboursement n'est enregistré. Si Yoco signale le remboursement comme en attente, WooCommerce indique qu'il est toujours en attente et n'enregistre rien. Ne le relancez pas : il sera ajouté à la commande lorsque Yoco le confirmera par webhook.

Les remboursements effectués dans le portail Yoco arrivent par le webhook refund.succeeded et sont enregistrés automatiquement comme remboursements WooCommerce, sans remettre les articles en stock. Un remboursement supérieur au montant restant à rembourser n'est pas enregistré, et une note vous invite à vérifier la commande. Un remboursement échoué ajoute une note indiquant que l'argent n'a pas été restitué au client.

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 > Yoco. 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, et 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, Yoco n'est pas proposé aux clients à la caisse. Si un paiement est tout de même lancé, 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 que vous puissiez 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 affecté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

Yoco n'apparaît pas à la caisse : vérifiez que la licence est active, que Enable/Disable est activé et que le mode actuel dispose d'une clé secrète : Test secret key en mode test, Live secret key en mode réel. La devise de la boutique ou de la commande 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é est manquante ou que la devise n'est pas le ZAR.

Le paiement a abouti, mais la commande reste Pending payment : le webhook ne fonctionne pas. Ouvrez la section Webhooks des réglages et vérifiez le statut du mode que vous utilisez. 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 confirmée lorsque le client revient sur la boutique après le paiement, et lorsqu'il tente de payer à nouveau.

Impossible d'enregistrer le webhook : les paiements sont tout de même confirmés lorsque les clients reviennent sur la boutique. Corrigez la raison indiquée dans le message, par exemple le site 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, source wcp_yoco_pay. 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 mode. timestamp outside the tolerance signifie que l'horloge du serveur est incorrecte : les signatures sont acceptées dans les 5 minutes par rapport à l'heure du serveur. checkout not completed yet — retry et could not confirm the checkout with Yoco — retry sont temporaires ; Yoco renvoie le webhook.

The secret key must start with sk_test_ / sk_live_ error on save: 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 lors de la passation de commande : lisez les notes de commande ou WooCommerce > Status > Logs, source wcp_yoco_pay. 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 vérifié : une tentative précédente a été payée avec un montant différent, ou après l'annulation de la commande. Lisez la note de commande, puis traitez 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 WooCommerce. Si Yoco a bien traité le remboursement, relancez le même remboursement : il ne sera pas remboursé deux fois.

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.

Désinstallation

La désactivation de l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et le statut de licence de cette extension sont toujours supprimés. Les réglages de la passerelle, les enregistrements de webhooks chez Yoco et les journaux, y compris les fichiers de journal archivés, ne sont supprimés que si Delete data était activé. Sinon, ils sont conservés pour une future réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

Yoco est une marque appartenant à son propriétaire respectif. Cette extension n'est pas affiliée à Yoco et n'est pas approuvée par elle.