VibeFox Ozow for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur. Le module refuse de s'installer sur les versions antérieures de PHP.

Devise : rand sud-africain (ZAR). Le mode de paiement n'est affiché que pour les paniers en ZAR. Ozow facture en centimes entiers ; la devise doit donc utiliser 2 décimales.

Compte Ozow : un compte marchand Ozow avec le Site Code et la Private Key de votre site Ozow, disponibles 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 boutique doit être accessible depuis Internet, sans protection par mot de passe ni pare-feu bloquant Ozow, afin que les notifications d'Ozow arrivent. La notification est acceptée même lorsque la boutique est en mode maintenance.

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échargement terminé, cliquez sur Configure, ou retrouvez plus tard VibeFox Ozow Pay 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. Saisissez le Site Code et la Private Key, ainsi que de préférence l'API Key, depuis votre tableau de bord marchand Ozow.

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

À l'installation, le module crée deux statuts de commande : Awaiting Ozow payment et Ozow payment on hold. PrestaShop propose un nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les restreindre dans Payment > Preferences ; ZAR doit y être autorisé pour le module. Un pays activé plus tard doit aussi être coché pour le module à cet endroit.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Ozow Pay > Configure. Chaque section avec un bouton Save enregistre la page entière. Au-dessus des champs, la page vous avertit lorsque le Site Code ou la Private Key manque (Ozow est alors masqué au paiement), lorsque la devise par défaut de la boutique n'est pas ZAR, lorsque la devise a plus de 2 décimales (passez-la à 2 dans International > Localization > Currencies), et affiche Test mode is on: no real payments are accepted. Do not ship orders paid in test mode. tant que le mode test est activé.

Ozow

Enable/Disable : Enable Ozow payments active ou désactive le mode de paiement. Par défaut : off.

Title : le nom du mode de paiement affiché aux clients au moment du paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Instant EFT (Ozow).

Description : le texte affiché sous le mode de paiement au moment 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 (seulement si la description n'est pas vide).

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 complet, pour ce panier, avec le même montant, la même devise et le même Site Code.

Les clés enregistrées ne sont jamais réaffichées. 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 Private Key ou API Key puis enregistrez pour supprimer une clé enregistrée. Un champ vide conserve la valeur enregistrée.

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 un message 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 : on.

Notifications de paiement

Les URL de notification, de succès, d'annulation et d'erreur sont envoyées à Ozow à chaque paiement ; rien n'est donc à configurer dans le tableau de bord Ozow, sauf si votre site Ozow est configuré avec des URL fixes. La section affiche les quatre URL : Notification URL, Success URL, Cancel URL et Error URL. Ce sont des liens de module de votre boutique (contrôleurs notify et return). Si votre site Ozow utilise des URL fixes, copiez-les exactement telles que les réglages les affichent.

Avancé

Debug log : enregistre les demandes de paiement et les réponses d'Ozow dans logs/ozow_p_debug.log.php, dans le dossier du module (non lisible depuis le web). Les erreurs et avertissements sont toujours journalisés. Les clés, hachages, jetons et données clients ne sont jamais journalisés. Par défaut : off.

Log : affiche la taille actuelle et la fin du journal, avec un bouton Clear log.

Delete data on uninstall : supprime les réglages et les journaux de ce module lors de la désinstallation (les données Ozow enregistrées sur les commandes sont conservées). Par défaut : off.

Paiement

Au moment du paiement, le client choisit le mode de paiement (par défaut Instant EFT (Ozow)) et confirme la commande. Le module envoie le client vers la page de paiement hébergée d'Ozow avec une demande signée pour le total du panier en ZAR. La référence du relevé bancaire est Cart, suivie du numéro du panier (jusqu'à 20 lettres latines, chiffres, espaces et tirets). Le nom du client est transmis à Ozow. Aucune commande n'existe encore à ce stade. 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 contiennent la même réponse signée et sont traités de la même manière, de sorte que la commande est créée même si l'un des deux se perd. La commande n'est marquée 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 appartenir à cette tentative de paiement du panier, et le montant et la devise doivent correspondre au panier. Avec une API Key, le paiement est également vérifié via l'API GetTransaction.

Après un paiement réussi, le client voit la page standard de confirmation de commande. Si Ozow ou la banque examine encore 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 un paiement examiné échoue plus tard ou si la commande non payée est annulée, elle indique Your Ozow payment was not completed. Please contact us about this order. Si Ozow n'a pas encore confirmé le paiement lorsque le client revient, une page affiche le texte d'attente avec les boutons Check again et Back to checkout.

Si le client annule sur la page d'Ozow ou si le paiement échoue, aucune commande n'est créée. Le client revient au paiement avec le même panier et voit 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.

Si le panier n'est pas en ZAR, le client voit Ozow accepts payments in South African rand (ZAR) only. Please choose another payment method.

Le module ne prend que les paiements uniques en ZAR. Il ne permet pas de rembourser depuis PrestaShop, ni les abonnements, ni les comptes bancaires enregistrés ou la tokenisation, ni l'envoi de liens de paiement depuis le back office.

Commandes et remboursements

Statuts de commande

Pas encore de commande : le client a été envoyé vers Ozow et n'a pas payé, a annulé, ou Ozow n'a pas encore confirmé le paiement. Seul le panier existe.

Payment accepted : le paiement a été confirmé. Le message de commande indique le montant et l'identifiant de transaction Ozow, ainsi que la confirmation éventuelle par l'API GetTransaction. L'identifiant de transaction du paiement de la commande est le TransactionId d'Ozow. Un paiement de test reçoit le message TEST MODE — no money was received, do not ship this order.

Awaiting Ozow payment : Ozow ou la banque examine le paiement. La commande est mise à jour lorsque Ozow envoie le statut final.

Ozow payment on hold : le message de commande indique la raison : le montant ou la devise payé diffère du panier ; 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.

Erreur de paiement : un paiement en cours d'examen a été annulé, abandonné ou a échoué. Une réponse positive ultérieure d'Ozow pour ce paiement marque tout de même la commande comme payée.

Une commande déjà payée n'est jamais modifiée en retour, et une commande annulée ou remboursée n'est jamais rouverte. Si un second paiement arrive pour une commande déjà payée, un message 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 ainsi, un paiement ultérieur ajoute seulement un message, et vous passez vous-même la commande en Payment accepted.

Bloc de paiement Ozow

La page de commande affiche un bloc Ozow payment avec la référence et la tentative de transaction, l'identifiant de transaction Ozow, le statut, le montant demandé, le montant indiqué par Ozow, le message d'Ozow et une mention TEST MODE pour les paiements de test.

Remboursements

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

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Ozow Pay est le premier bloc de Modules > Module Manager > VibeFox Ozow Pay > 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 de fin de validité de la licence 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-ozow 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 l'emplacement dans votre compte vibefox.net.

Sans clé active, Ozow n'est pas affiché 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. 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 pas le tester à la caisse. Un rappel apparaît dans Modules > Module Manager, sur l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés.

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 que vous travaillez 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

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 du panier est ZAR. Dans Payment > Preferences, vérifiez que le module est autorisé pour ZAR, pour le pays du client et pour son groupe. La page des réglages affiche un avertissement lorsqu'un élément manque.

Le paiement a abouti, mais aucune commande n'a été créée : la notification d'Ozow n'a pas atteint la boutique et le client n'est pas revenu. Vérifiez que votre boutique est accessible depuis Internet (sans protection par mot de passe ni pare-feu bloquant Ozow). Si votre site Ozow est configuré avec des URL fixes, vérifiez qu'elles sont exactement celles affichées dans Payment notifications. Activez Debug log et lisez le journal sur la page Configure.

La notification répond Invalid hash : la Private Key des réglages n'appartient pas au site Ozow qui a envoyé la réponse. Copiez-la à nouveau depuis le tableau de bord marchand Ozow. Rien n'est modifié.

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 pas à un paiement lancé dans 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 Payment not confirmed yet : la réponse n'a pas encore pu être appliquée. 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). C'est aussi la réponse lorsque le retour du client était en cours de traitement pour le même panier au même moment, ou lorsque la commande n'a pas pu être créée ; consultez le journal.

Un paiement de test n'a pas réglé la commande : le module est en mode réel. Les paiements de test ne règlent jamais une commande en mode réel ; le message de commande ou le journal l'indique.

La commande est en Ozow payment on hold après le paiement : lisez le message de commande, vérifiez le paiement dans votre tableau de bord Ozow, puis passez la commande en Payment accepted ou remboursez le paiement dans Ozow.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Ozow Pay et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete data on uninstall est activé, les réglages du module et le journal sont supprimés. S'il est désactivé, tous les réglages sont conservés pour une réinstallation ultérieure. Les enregistrements de paiement Ozow et les statuts de commande Awaiting Ozow payment et Ozow payment on hold sont toujours conservés, de sorte que les notifications tardives concernant d'anciennes commandes restent reconnues après une réinstallation. Les commandes existantes conservent leurs messages de paiement et leurs identifiants de transaction.

Ozow est une marque de son propriétaire respectif. Ce module n'est pas affilié à Ozow et n'est pas approuvé par Ozow.