VibeFox DPO for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

PHP : 8.0 ou ultérieur avec l'extension SimpleXML. Le module refuse de s'installer sans elles.

Compte DPO Pay : vous avez besoin du Company Token et du Service Type ID de votre compte marchand DPO. DPO les délivre à l'ouverture de votre compte ; demandez-les à votre gestionnaire de compte DPO ou sur dpogroup.com. DPO peut aussi fournir un compte de test avec son propre token et son propre type de service. Il n'existe pas de serveur de test séparé : DPO utilise la même adresse d'API pour les comptes de test et de production, et le compte est choisi par le token.

Devise : la devise de la boutique doit être prise en charge par votre compte DPO. DPO accepte au maximum 2 décimales, donc les totaux de panier à 3 décimales (par exemple KWD 12.345) ne peuvent pas être payés.

Cron du serveur : une tâche cron qui appelle l'URL de revérification du module toutes les 15 minutes (voir Configuration).

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 l'envoi terminé, cliquez sur Configure, ou retrouvez VibeFox DPO Pay Gateway dans la liste des modules plus tard et cliquez sur Configure.

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

4. Saisissez le Company Token et le Service Type de test et/ou de production (voir Configuration).

5. Envoyez l'URL de notification push affichée sur la page Configure au support DPO et demandez-lui de la configurer pour votre compte. Ajoutez l'URL du cron aux tâches cron de votre serveur.

6. Activez Enable/Disable et cliquez sur Save. Passez une commande de test en mode test, puis désactivez Test mode pour accepter des paiements réels.

À l'installation, le module crée le statut de commande DPO 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 limiter dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox DPO Pay Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Lorsque le module est activé mais que le Company Token ou le Service Type du mode sélectionné est vide, la page vous avertit que le mode de paiement est masqué au moment de la commande, et l'enregistrement affiche le même avertissement. Tant que le mode test est activé, la page affiche Test mode is on: payments are created with the test account credentials.

DPO Pay

Enable/Disable : Enable DPO Pay 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 la commande. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : DPO Pay. Obligatoire.

Description : le texte affiché sous le mode de paiement au moment de la commande. Par défaut : Pay securely by card or mobile money on the DPO Pay payment page.

Identifiants API

DPO délivre un Company Token et un Service Type ID pour votre compte marchand, et d'autres distincts pour un compte de test. Demandez-les à votre gestionnaire de compte DPO ou sur dpogroup.com.

Test mode : lorsqu'il est activé, les nouveaux paiements sont créés avec le Company Token et le Service Type de test. Par défaut : activé. Désactivez-le pour accepter des paiements réels avec les identifiants de production. Les vérifications de statut et les annulations des paiements existants utilisent toujours le compte avec lequel le paiement a été créé.

Test Company Token : le Company Token de votre compte de test DPO.

Test Service Type : le Service Type ID numérique de votre compte de test DPO.

Live Company Token : le Company Token de votre compte marchand DPO de production.

Live Service Type : le Service Type ID numérique de votre compte marchand DPO de production.

Les Company Tokens 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. Un Service Type doit être un nombre. Toute autre valeur n'est pas enregistrée : la page affiche un avertissement et conserve la valeur précédente.

Clear saved Company Tokens : cochez un token et cliquez sur Save pour le supprimer. Un champ vide conserve la valeur enregistrée.

Notifications de paiement

Push notification URL : la notification push informe immédiatement votre boutique qu'un paiement a été effectué, même si le client ferme le navigateur après avoir payé. L'URL ne se règle pas dans un tableau de bord : demandez au support DPO de la configurer pour votre compte. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_dpo_pay/notify, éventuellement avec un code de langue. Copiez-la exactement comme la page l'affiche. Elle doit être accessible depuis Internet, sans mode maintenance, pare-feu ni authentification de base devant elle.

Les notifications push de DPO ne sont pas signées, leur contenu n'est donc jamais considéré comme fiable. Le module ne les utilise que pour retrouver le paiement grâce à son jeton de transaction, puis vérifie le résultat auprès de DPO lui-même. Un jeton que votre boutique n'a pas créé est rejeté sans aucune requête vers DPO.

Scheduled status re-check (cron) : appelez cette URL toutes les 15 minutes depuis une tâche cron du serveur, par exemple avec curl. Les paiements non confirmés sont revérifiés auprès de DPO 15 minutes après la redirection, puis de nouveau après le délai de paiement. L'URL contient un jeton secret, gardez-la donc privée. Sans l'URL push et le cron, une commande n'est créée que lorsque le client revient dans la boutique après avoir payé.

Commandes

Successful payment status : le statut de commande après un paiement réussi et vérifié.

Les écarts de montant ou de devise, les paiements seulement autorisés et les transactions sur- ou sous-payées vont toujours en DPO payment on hold.

Avancé

Logging : enregistre les appels à l'API et les notifications dans logs/dpo_p_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours journalisées. Les jetons sont masqués, aucune donnée client n'est journalisé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 : lorsqu'il est activé, la désinstallation du module supprime ses réglages et le journal. Les données DPO enregistrées pour les commandes et le statut de commande DPO payment on hold sont toujours conservés. Désinstaller sans cette option ne supprime jamais de données. Par défaut : désactivé.

Commande

À l'étape de paiement, le client choisit le mode de paiement (par défaut DPO Pay) et voit la note You will be redirected to the secure DPO Pay payment page. Après confirmation, le module crée une transaction DPO pour le montant total du panier dans la devise du panier, avec le numéro de panier et le nom de votre boutique comme description, puis envoie le client vers la page de paiement DPO. Le nom, l'e-mail, le téléphone et l'adresse de facturation du client sont transmis pour préremplir la page. Là, le client paie avec n'importe quelle méthode activée sur votre compte DPO. Le lien de paiement reste valable 5 heures. À ce stade, aucune commande n'existe encore.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée payée qu'une fois DPO la confirme : le module demande à DPO le résultat de la transaction lorsque le client revient, lorsqu'une notification push arrive et lors des vérifications programmées. La commande est alors créée et le client voit la page standard de confirmation de commande.

Si le paiement n'est pas confirmé, le client revient à l'étape de commande avec l'un de ces messages. Le panier est conservé.

Si le client clique sur le bouton de la page DPO pour revenir à la boutique, la transaction est d'abord vérifiée. Si elle a été payée, la commande est créée. Sinon, elle est annulée chez DPO et le client revient à l'étape de commande avec son panier.

Lorsque le client paie à nouveau pour le même panier, la transaction DPO précédente est d'abord vérifiée. Si elle a été payée, la commande est créée sans second débit. Si elle est encore en cours de traitement, le client voit Your previous payment for this order is still being processed by DPO. Please wait a few minutes before trying again. Sinon, l'ancienne transaction est annulée chez DPO et une nouvelle est créée.

Si DPO ne peut pas lancer le paiement, le client reste à l'étape de commande avec un message bref choisi selon le code d'erreur DPO, par exemple DPO Pay does not support the currency of this order. Please choose another payment method. ou The amount exceeds the limit allowed by DPO Pay. Please choose another payment method or contact us. Les autres erreurs affichent DPO Pay is temporarily unavailable. Please try again or choose another payment method. La raison technique est écrite dans le journal.

La notification push et l'URL du cron fonctionnent pendant que la boutique est en mode maintenance et ne sont pas bloquées par la restriction géographique de votre boutique.

Le module n'accepte que les paiements uniques sur la page DPO. Il ne propose ni remboursements depuis la boutique, ni cartes enregistrées, ni abonnements ou paiements récurrents, ni champs de carte sur votre site, ni capture de paiements seulement autorisés.

Commandes

Statuts de commande

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

Payment accepted, Delivered or DPO payment on hold : le paiement a été vérifié. Le statut suit Successful payment status. Le paiement est enregistré avec le jeton de transaction DPO comme identifiant de transaction. Une note privée sur la page de la commande affiche le montant, la devise, le code d'approbation et le début du jeton.

DPO payment on hold after payment : DPO a confirmé un paiement, mais le montant ou la devise diffère du panier, le paiement est seulement autorisé et non capturé, la transaction a été sur- ou sous-payée, ou le client avait annulé le paiement ou la commande était déjà annulée. La note privée explique la raison. Vérifiez la transaction dans le portail DPO. Capturez ou annulez un paiement seulement autorisé dans le portail DPO, puis mettez à jour le statut de la commande.

Cancelled : lorsque vous annulez une commande non payée du module (par exemple une commande en attente pour un paiement seulement autorisé), sa transaction DPO ouverte est aussi annulée chez DPO.

Un résultat de refus arrivé plus tard ne modifie jamais une commande, et les résultats des anciennes transactions ne font jamais échouer la tentative en cours. Si DPO confirme un second paiement réussi pour une commande déjà payée, la commande n'est pas modifiée et reçoit une note signalant un possible double paiement, afin que vous puissiez le rembourser dans le portail DPO. Une commande payée ou remboursée n'est jamais rouverte.

Remboursements

Les remboursements depuis la boutique ne sont pas disponibles dans cette version. Remboursez le paiement dans le portail marchand DPO, puis modifiez le statut de la commande dans PrestaShop.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox DPO Pay Gateway est le premier bloc de Modules > Module Manager > VibeFox DPO Pay Gateway > Configure, au-dessus des réglages. Collez 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-dpo 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, DPO Pay n'est pas proposé aux clients au moment de la commande. 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, donc le moyen de paiement est aussi masqué pour vous : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au moment de la commande. 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.

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 la licence.

Dépannage

DPO Pay does not appear at checkout : vérifiez que la licence est active, que Enable/Disable est activé et que le Company Token et le Service Type du mode sélectionné sont renseignés : les champs de test en mode test, les champs de production sinon. La page des réglages affiche un avertissement lorsqu'ils manquent. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client.

The payment went through, but no order was created : l'URL de notification push n'est probablement pas configurée pour votre compte DPO, et le client n'est pas revenu dans la boutique. Demandez au support DPO de configurer l'URL affichée dans les réglages, et vérifiez que le cron appelle l'URL de revérification toutes les 15 minutes. Activez Logging et consultez le champ Log sur la page du module.

Push notification answers Unknown transaction : le jeton de transaction n'appartient à aucun paiement DPO Pay de cette boutique, par exemple parce que la notification provient d'une autre boutique du même compte DPO.

Push notification answers Verification failed : DPO n'a pas pu être joint pour vérifier le paiement, le panier était en cours de traitement par une autre requête au même moment, ou la commande n'a pas pu être créée (par exemple parce que le module est désactivé). DPO renvoie la notification, et la revérification programmée confirme aussi la commande. La raison figure dans le journal.

The push URL shows Method not allowed in the browser : c'est normal. L'URL n'accepte que les requêtes provenant de DPO.

The cron URL answers Forbidden : le jeton dans l'URL est incorrect. Copiez de nouveau l'URL depuis la page Configure. Un appel réussi répond OK checked= suivi du nombre de paiements vérifiés.

The Service Type is not saved : il doit s'agir du Service Type ID numérique fourni par DPO.

The customer sees DPO Pay is temporarily unavailable : DPO a refusé de créer la transaction, par exemple à cause d'un Company Token ou d'un Service Type incorrect, ou d'un token de l'autre mode. Le code de résultat DPO figure dans le journal.

The customer sees that DPO accepts at most 2 decimal places : le total du panier a 3 décimales. DPO ne peut pas débiter de tels montants.

The customer sees This order has already been paid with DPO Pay : DPO a refusé un second paiement pour le même panier. Vérifiez le paiement dans le portail DPO et la commande dans PrestaShop.

Order is DPO payment on hold after payment : lisez la note privée sur la page de la commande (voir Statuts de commande), puis vérifiez la transaction dans le portail DPO.

Les développeurs peuvent modifier les données client envoyées à DPO avec le hook actionWcpDpoPayCustomerData, et le délai de paiement avec actionWcpDpoPayPaymentTimeLimit.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox DPO Pay Gateway et choisissez Uninstall. La clé de licence et le statut de la licence de ce module sont toujours supprimés. Si Delete data 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 future réinstallation. Les données DPO enregistrées pour les commandes et le statut de commande DPO payment on hold sont toujours conservés, afin que les notifications tardives pour d'anciens paiements continuent de fonctionner après une réinstallation. Les commandes existantes conservent leurs notes de paiement et leurs identifiants de transaction.

DPO Pay est une marque déposée de son propriétaire. Ce module n'est pas affilié à DPO Pay et n'est pas approuvé par DPO Pay.