VibeFox Ozow for WooCommerce — Aide

Prérequis

WordPress : 6.2 ou ultérieur.

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

PHP : 8.0 ou ultérieur.

Devise : rand sud-africain (ZAR). Le mode de paiement est masqué pour les autres devises. Ozow facture des centimes entiers ; WooCommerce doit donc utiliser 2 décimales.

Compte Ozow : un compte marchand Ozow avec le Site Code et la Private Key de votre site Ozow, à récupérer dans votre tableau de bord marchand Ozow. L'API Key est facultative, mais recommandée. Ozow utilise le même Site Code et les mêmes clés pour les paiements de test et les paiements réels.

Site accessible : votre site doit être accessible depuis Internet, sans mode maintenance, sans protection par mot de passe et sans pare-feu bloquant Ozow, afin que les notifications d'Ozow parviennent bien.

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_ozow_pay dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > Ozow > Manage, ou cliquez sur Settings sous le nom de l'extension dans 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 le Site Code et la Private Key, ainsi que, de préférence, l'API Key, depuis votre tableau de bord marchand Ozow.

6. Activez Enable/Disable. Effectuez un paiement de test avec Test mode activé, puis désactivez le mode test pour accepter les paiements réels.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Ozow. Au-dessus des champs, la page vous avertit lorsque le Site Code ou la Private Key manque (Ozow est alors masqué au moment du paiement), lorsque la devise de la boutique n'est pas le ZAR, et lorsque WooCommerce utilise plus de 2 décimales. Elle affiche aussi Test mode is on: no real payments are accepted. Do not ship orders paid in test mode. tant que le mode test est activé. Dans la liste des modes de paiement, Ozow est signalé comme nécessitant une configuration tant que le Site Code et la Private Key ne sont pas renseignés.

Général

Enable/Disable : Enable Ozow payments 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 moment de payer. Par défaut : Instant EFT (Ozow).

Description : le texte affiché sous le mode de paiement lors du paiement. Par défaut : Pay instantly and securely from your South African bank account. You will be redirected to Ozow to choose your bank and approve the payment. En mode test, la ligne TEST MODE: no money will be charged. est ajoutée dessous.

Identifiants Ozow

Copiez le Site Code, la Private Key et l'API Key depuis votre tableau de bord marchand Ozow (Merchant details / Sites). La section renvoie à la documentation d'intégration d'Ozow sur hub.ozow.com.

Site Code : le Site Code du site Ozow qui reçoit les paiements. Les réponses pour un autre Site Code sont rejetées.

Private Key : signe chaque demande de paiement et vérifie chaque réponse d'Ozow. Gardez-la confidentielle. Sans elle, le mode de paiement est masqué et aucune réponse d'Ozow n'est acceptée.

API Key (recommended) : facultative. Avec une API Key, chaque paiement réussi est aussi confirmé par l'API GetTransaction d'Ozow avant que la commande soit marquée comme payée. L'API doit indiquer que le paiement est terminé, pour cette commande, avec le même montant, la même devise et le même Site Code.

Test mode : Enable Ozow test mode. Ozow utilise le même Site Code et les mêmes clés pour les tests : les paiements sont créés avec IsTest=true et aucun argent ne circule. Les commandes payées en mode test reçoivent une note de commande ; ne les expédiez pas. Désactivez le mode test pour accepter les paiements réels. Un paiement de test ne règle jamais une commande en mode réel. Par défaut : activé.

Notifications de paiement

Les URL de notification, de succès, d'annulation et d'erreur sont envoyées à Ozow à chaque paiement ; il n'y a donc rien à configurer dans le tableau de bord Ozow, sauf si votre site Ozow est configuré avec des URL fixes. La section affiche l'URL de notification. Elle ressemble à https://your-site/wc-api/ozow_pay/?ozow_notify=1. Si votre site Ozow utilise des URL fixes, copiez-la exactement telle qu'elle apparaît dans les réglages.

Avancé

Debug log : Log payment requests and Ozow responses écrit les détails dans WooCommerce > Status > Logs, source wcp_ozow_pay. Les erreurs et les avertissements sont toujours journalisés. Les clés, les hachages et les données clients ne sont jamais journalisés. Par défaut : désactivé.

Delete data on uninstall : Remove the settings and logs of this plugin when it is deleted (Ozow data saved on orders is kept). Par défaut : désactivé.

Paiement

Le client choisit le mode de paiement (par défaut Instant EFT (Ozow)) et passe commande. L'extension envoie le client vers la page de paiement hébergée d'Ozow, avec une demande signée pour le total de la commande en ZAR. La référence qui apparaît sur le relevé bancaire est Order, suivie du numéro de commande (jusqu'à 20 lettres latines, chiffres, espaces et tirets). Le nom du client est transmis à Ozow. Sur la page d'Ozow, le client choisit une banque sud-africaine et approuve le paiement dans son application bancaire.

Ozow notifie ensuite la boutique et renvoie le client. Les deux transmettent la même réponse signée et sont traitées de la même manière, de sorte que la commande est mise à jour même si l'une des deux se perd. La commande n'est marquée comme payée qu'après confirmation d'Ozow : le hachage doit être vérifié avec votre Private Key, le Site Code doit être le vôtre, la réponse doit contenir la clé de cette commande, et le montant et la devise doivent correspondre à la commande. Avec une API Key, le paiement est en outre vérifié par l'API GetTransaction.

Après un paiement réussi, le client arrive sur la page de confirmation de commande. Si Ozow n'a pas encore confirmé le paiement, la page indique We are waiting for Ozow to confirm your payment. You will receive an e-mail as soon as it is confirmed — there is no need to pay again. Si la commande est en attente, elle indique Your Ozow payment was received and is being reviewed by the store. We will contact you if anything is needed.

Si le client annule sur la page d'Ozow ou si le paiement échoue, la commande passe à Échoué et le client revient sur la page Pay for order avec The Ozow payment was cancelled. You can try again or choose another payment method. ou The Ozow payment was not completed. You can try again or choose another payment method. Le client peut payer à nouveau la même commande.

Le mode de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order (uniquement pour les commandes en ZAR). Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).

L'extension ne prend que les paiements uniques en ZAR. Elle ne propose ni remboursements depuis WooCommerce, ni abonnements, ni comptes bancaires enregistrés ou tokenisation, ni envoi de liens de paiement depuis l'administration.

Commandes

Statuts de commande

Pending payment : le client a été envoyé vers Ozow et n'a pas encore payé, ou Ozow n'a pas encore confirmé le paiement.

Processing : le paiement a été confirmé. C'est le statut WooCommerce standard après paiement ; les commandes ne contenant que des produits virtuels téléchargeables passent à Completed. La note de commande indique le montant et l'ID de transaction Ozow, ainsi que la confirmation du paiement par l'API GetTransaction. L'ID de transaction de la commande est le TransactionId d'Ozow. Un paiement de test reçoit la note TEST MODE — no money was received, do not ship this order.

On hold : la note de commande indique la raison. Ozow ou la banque examine le paiement (la commande est mise à jour lorsqu'Ozow envoie le statut final) ; le montant ou la devise payés diffèrent de la commande ; un paiement est arrivé pour une commande déjà annulée ; ou, avec une API Key, l'API GetTransaction n'a pas encore pu confirmer le paiement ou le contredit. Vérifiez le paiement dans votre tableau de bord Ozow et modifiez le statut de la commande. Si l'API n'a pas pu répondre, la notification suivante d'Ozow finalise la commande.

Failed : le client a annulé le paiement, celui-ci a été abandonné ou Ozow a signalé une erreur. Le client peut payer à nouveau depuis la commande.

Une commande déjà payée n'est jamais remise en arrière, et une commande annulée ou remboursée n'est jamais rouverte. Si un second paiement arrive pour une commande déjà payée, une note vous invite à rembourser le doublon dans votre tableau de bord Ozow. Si une commande est en attente pour une autre raison, par exemple parce que vous l'avez mise en attente, un paiement ultérieur ajoute seulement une note, et c'est vous qui passez la commande en Processing.

Remboursements

Les remboursements depuis WooCommerce ne sont pas pris en charge. Remboursez le paiement dans votre tableau de bord marchand Ozow, puis enregistrez le remboursement manuellement dans WooCommerce.

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 > Ozow. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date de fin de validité de la licence 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 cet emplacement depuis votre compte vibefox.net.

Sans clé active, Ozow n'est pas proposé aux clients au moment du paiement. 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 mode 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 concernées : les paiements déjà lancés sont toujours confirmés.

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

Dépannage

Ozow n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable/Disable est activé, que le Site Code et la Private Key sont renseignés et que la devise de la boutique ou de la commande est le ZAR. 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 : la notification d'Ozow n'a pas atteint la boutique et le client n'est pas revenu. Vérifiez que votre site est accessible depuis Internet (sans mode maintenance, sans protection par mot de passe et sans pare-feu bloquant Ozow). Si votre site Ozow utilise des URL fixes, vérifiez que l'URL de notification est exactement celle affichée dans les réglages. Activez Debug log et consultez WooCommerce > Status > Logs, source wcp_ozow_pay.

La notification répond Invalid hash : la Private Key enregistrée dans les réglages n'appartient pas au site Ozow qui a envoyé la réponse. Copiez-la de nouveau depuis votre tableau de bord marchand Ozow.

La notification répond Unknown site : la réponse provient d'un autre site Ozow. Vérifiez le Site Code.

La notification répond Order mismatch ou Order not found : la réponse n'appartient à aucune commande de cette boutique. Rien n'est modifié.

La notification répond Gateway not configured : le Site Code ou la Private Key manque. Renseignez-les ; Ozow peut réessayer.

La notification répond Order busy : une autre réponse d'Ozow pour la même commande était en cours de traitement au même moment. La réponse n'est pas appliquée ; la notification suivante ou le retour du client l'appliquera.

La notification répond Payment not confirmed yet : avec une API Key, l'API GetTransaction n'a pas pu confirmer le paiement. La commande est en attente, et la notification suivante la finalise. Si elle reste en attente, vérifiez l'API Key et le paiement dans votre tableau de bord Ozow.

Le client voit Ozow accepts payments in South African rand (ZAR) only : la commande est dans une autre devise. Ozow ne peut pas être utilisé pour cette commande.

Un paiement de test n'a pas réglé la commande : la passerelle est en mode réel. Les paiements de test ne règlent jamais une commande en mode réel ; une note sur la commande le signale.

La commande est On hold après le paiement : lisez la note de commande et vérifiez le paiement dans votre tableau de bord Ozow, puis passez la commande en Processing ou remboursez le paiement dans Ozow.

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 depuis 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 autres options de l'extension et ses journaux 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 ID de transaction.

Ozow est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à Ozow ni approuvée par Ozow.