VibeFox SimplePay 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 de la boutique : HUF, EUR ou USD. SimplePay n'accepte pas les autres devises, et le mode de paiement n'est pas proposé pour les paniers dans ces devises.

Comptes marchands SimplePay : SimplePay fournit un compte marchand distinct pour chaque devise, et des comptes séparés pour la production et le sandbox. Pour chaque compte, vous avez besoin de son MERCHANT et de sa SECRET KEY, disponibles dans l'interface marchand de SimplePay (admin.simplepay.hu pour la production, sandbox.simplepay.hu pour le sandbox), account > Technical data. Si vous ne vendez qu'en HUF, le compte HUF suffit. Aucune autre clé n'est nécessaire.

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

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

4. Saisissez le MERCHANT et la SECRET KEY de vos comptes SimplePay pour chaque devise que vous vendez : comptes sandbox pour les tests et comptes de production pour les paiements réels (voir Configuration).

5. Copiez la IPN URL affichée sur la page Configure dans chaque compte marchand (production et sandbox) de l'interface marchand de SimplePay.

6. Activez Enable/Disable et cliquez sur Save. Testez un paiement avec Sandbox mode activé, puis désactivez Sandbox mode pour encaisser de vrais paiements.

À l'installation, le module crée le statut de commande SimplePay 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 SimplePay 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 par défaut de la boutique n'est pas prise en charge par SimplePay, ou lorsqu'elle n'a pas de compte marchand dans le mode actuel. Dans les deux cas, le mode de paiement n'est pas proposé pour les paniers dans cette devise. Tant que le mode sandbox est activé, la page affiche Sandbox mode is on: payments go to the SimplePay sandbox, no real money is charged.

SimplePay (OTP)

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

Description : le texte affiché sous le mode de paiement lors du paiement. Par défaut : Pay securely with your credit or debit card via SimplePay. Les marchands hongrois peuvent indiquer ici la déclaration de transfert de données SimplePay (avec son lien).

Sandbox mode : utilise le sandbox SimplePay pour les paiements de test avec les comptes sandbox. Il change à la fois l'adresse de l'API et les comptes marchands. Aucun argent réel n'est débité. Par défaut : activé. Désactivez-le pour encaisser de vrais paiements avec les comptes de production. Tant qu'il est activé, les clients voient Sandbox mode: no real payment is taken. sous le mode de paiement. Les commandes lancées dans le sandbox sont toujours remboursées dans le sandbox.

Comptes marchands de production

Les comptes utilisés lorsque Sandbox mode est désactivé. Renseignez les comptes des devises dans lesquelles votre boutique vend. Les valeurs MERCHANT et SECRET KEY se trouvent dans l'interface marchand de SimplePay (admin.simplepay.hu), account > Technical data. Un compte n'est utilisé que si ses deux champs sont renseignés.

HUF account — Merchant ID : le MERCHANT de votre compte HUF de production.

HUF account — Secret key : la SECRET KEY de votre compte HUF de production.

EUR account — Merchant ID et EUR account — Secret key : idem pour votre compte EUR de production.

USD account — Merchant ID et USD account — Secret key : idem pour votre compte USD de production.

Comptes marchands sandbox

Les comptes utilisés lorsque Sandbox mode est activé. Les champs sont les mêmes que pour les comptes de production : HUF account — Merchant ID, HUF account — Secret key, et les mêmes paires pour EUR et USD. Prenez les valeurs dans l'interface marchand sandbox de SimplePay (sandbox.simplepay.hu), account > Technical data.

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

IPN URL

L'IPN est le message que SimplePay envoie à votre boutique lorsque le statut du paiement change. C'est le moyen habituel de créer une commande. La section affiche l'URL IPN de votre boutique. Avec les URL conviviales, elle ressemble à https://your-shop/module/wcp_simplepay_gateway/ipn, éventuellement avec un code de langue comme /en/. Renseignez cette URL pour chaque compte marchand, production et sandbox, dans l'interface marchand de SimplePay. Copiez l'URL exactement telle qu'affichée dans les réglages, car un IPN redirigé est perdu.

L'IPN doit être signé avec la SECRET KEY du compte marchand qu'il désigne, dans le mode (sandbox ou production) dans lequel le paiement a été lancé. Les IPN sans signature valide sont rejetés. Le module confirme chaque IPN valide à SimplePay, sous la forme signée qu'exige SimplePay. Les statuts IPN suivants sont utilisés :

FINISHED : le paiement a réussi. La commande est créée après le contrôle du montant et de la devise.

NOTAUTHORIZED, FRAUD : le paiement a été refusé. La tentative de paiement est marquée comme échouée ; aucune commande n'est créée.

TIMEOUT, CANCELLED : le délai de paiement a expiré ou le client a annulé. La tentative de paiement est marquée comme expirée ou annulée ; aucune commande n'est créée.

Les statuts refusé, annulé et expiré ne sont enregistrés que pour la dernière tentative de paiement d'un panier qui n'a pas encore de commande. Les autres statuts sont journalisés et ne changent rien. Sans IPN, une commande n'est créée que lorsque le client revient dans la boutique après un paiement réussi.

Clear saved secret keys : cochez une clé secrète et cliquez sur Save pour la supprimer. Un champ vide conserve la valeur enregistrée.

Commandes

Order Status After Payment : le statut de commande attribué après un paiement réussi.

Processing (Payment accepted) : la valeur par défaut, le statut PrestaShop standard des commandes payées.

Completed (Delivered) : chaque commande payée passe au statut Livré.

Un paiement d'un montant ou d'une devise différents de ceux de la commande passe toujours en SimplePay payment on hold.

Avancé

Logging : enregistre les appels à l'API, les IPN et les retours dans logs/simplepay_op_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les clés et les données clients ne sont pas journalisées. Les erreurs sont toujours journalisées, même lorsque l'option est désactivé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 on Uninstall : lorsqu'elle est activée, la désinstallation du module supprime les réglages de la passerelle et le journal. Les données de commande (transactions et remboursements SimplePay) sont toujours conservées. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le mode de paiement (par défaut SimplePay (Card Payment)) et voit la mention You will be redirected to the SimplePay payment page to pay by card. Après confirmation, le module lance un paiement par carte SimplePay pour le total du panier dans la devise du panier, avec le compte marchand de cette devise dans le mode actuel, et envoie le client vers la page de paiement SimplePay. L'e-mail du client et, lorsqu'elle est complète, l'adresse de facturation sont transmis à SimplePay. La page de paiement utilise la langue de la boutique lorsque SimplePay la prend en charge, sinon l'anglais. Un paiement lancé peut être effectué dans les 30 minutes. À ce stade, aucune commande n'existe encore.

Après un paiement réussi, le client revient dans votre boutique. Le retour seul ne paie jamais une commande : le module demande à SimplePay le statut de la transaction au moyen d'une requête signée, de sorte que la commande est créée même si l'IPN arrive en retard. La commande n'est marquée payée qu'après confirmation par SimplePay. Le client voit alors la page standard de confirmation de commande avec Successful transaction. SimplePay transaction ID: et l'identifiant. Si SimplePay n'a pas encore confirmé le paiement, une page Payment confirmation affiche Your payment is being confirmed by SimplePay. SimplePay transaction ID: avec l'identifiant et un bouton Check again ; l'IPN crée la commande dès son arrivée.

Si le paiement échoue, est annulé ou expire, le client est renvoyé au paiement avec le message de SimplePay et l'identifiant de transaction, par exemple Cancelled payment. You cancelled the payment ou Timeout. The time allowed to complete the payment has expired. En cas d'échec, le client est invité à vérifier les données saisies et à contacter sa banque émettrice de carte. Le panier est conservé et le client peut réessayer. Chaque nouvelle tentative reçoit sa propre référence SimplePay : PS, le numéro de panier et le numéro de tentative, par exemple PS123-1, PS123-2.

Si SimplePay ne peut pas lancer le paiement, le client voit The SimplePay payment could not be started. Please try again or choose another payment method. Si la devise du panier n'a pas de compte marchand, le message est SimplePay is not available for the currency of this order. Please choose another payment method. La raison technique est écrite dans le journal.

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

Le module ne prend que des paiements par carte uniques, encaissés sur la page SimplePay. Il ne gère ni cartes enregistrées ni paiements en un clic, ni abonnements ou paiements récurrents, ni autorisation et capture séparées.

Commandes et remboursements

Statuts de commande

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

Payment accepted or Delivered : le paiement a été confirmé. Le statut suit Order Status After Payment. Le paiement est enregistré avec l'identifiant de transaction SimplePay, et une note indique l'identifiant de transaction ainsi que la confirmation par l'IPN ou par la demande de statut.

SimplePay payment on hold : le total ou la devise du panier a été modifié après le lancement du paiement, de sorte que le montant payé diffère de la commande. Aucun paiement n'est enregistré. La note indique les deux montants. Vérifiez la commande et traitez-la, ou remboursez le paiement dans l'interface marchand de SimplePay. Si une autre tentative du même panier est ensuite payée pour le bon montant, la commande passe au statut payé.

Refunded : le paiement a été entièrement remboursé via le module.

Une commande payée, remboursée ou livrée n'est jamais rouverte par un IPN tardif. Si un second paiement réussit pour une commande déjà payée, la commande n'est pas modifiée. Une note vous demande de le vérifier dans l'interface SimplePay et de le rembourser s'il s'agit d'un doublon.

Bloc de paiement SimplePay

La page de commande affiche un bloc SimplePay payment avec l'identifiant de transaction, la référence de commande (orderRef), le compte marchand et le mode, le statut SimplePay, les montants payés et remboursés, un badge Sandbox pour les paiements sandbox, les tentatives de paiement du panier (lorsqu'il y en a eu plusieurs), l'historique des remboursements et les SimplePay notes de la commande.

Remboursements

Dans le bloc SimplePay payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via SimplePay (OTP). Confirmez la question Refund this amount via SimplePay? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez avoir le droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. Les remboursements en HUF doivent être des forints entiers. Le remboursement est envoyé pour la transaction SimplePay qui a payé la commande, avec son montant et sa devise, via le compte marchand et dans le mode (sandbox ou production) de ce paiement ; ce compte doit donc toujours figurer dans les réglages. Si SimplePay refuse le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec l'identifiant de transaction SimplePay du remboursement et le motif si vous en avez saisi un. Un remboursement total passe la commande en Refunded. Un remboursement partiel ne modifie pas le statut. Une commande mise en attente après un écart de montant ne peut pas être remboursée depuis le bloc : remboursez-la dans l'interface marchand de SimplePay.

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 SimplePay. Les remboursements effectués dans l'interface marchand de SimplePay ne sont pas synchronisés avec PrestaShop. Enregistrez-les manuellement.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox SimplePay Gateway est le premier bloc de Modules > Module Manager > VibeFox SimplePay 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 valable 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-simplepay 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, SimplePay n'est pas affiché 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. La vitrine PrestaShop ne sait pas que vous êtes connecté au back office : le mode de paiement est donc masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au moment du paiement. Un rappel apparaît dans Modules > Module Manager, dans l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés par l'IPN, 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

SimplePay n'apparaît pas au moment du paiement : vérifiez que la licence est active, que Enable/Disable est activé, que la devise du panier est HUF, EUR ou USD, et que cette devise dispose de Merchant ID et de Secret key dans le mode actuel : les comptes sandbox tant que Sandbox mode est activé, les comptes de production tant qu'il est désactivé. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client.

Le paiement a abouti, mais aucune commande n'a été créée : l'IPN n'a pas atteint la boutique. Dans l'interface marchand de SimplePay, vérifiez l'IPN URL du compte marchand utilisé (production ou sandbox, selon la devise du panier). Elle doit être exactement l'URL affichée dans les réglages, et votre serveur doit être joignable depuis Internet. La commande est aussi créée lorsque le client revient dans la boutique après le paiement.

L'IPN répond Invalid signature : l'IPN désigne un compte marchand absent des réglages, sa Secret key est incorrecte, ou il est signé avec le compte de l'autre mode que celui du paiement. Saisissez le MERCHANT et la SECRET KEY exactement comme les affiche l'interface marchand de SimplePay. SimplePay renvoie les IPN non confirmés.

L'IPN répond Order not found ou Unknown transaction : l'IPN concerne un paiement que cette boutique n'a pas lancé. Rien n'est modifié.

L'IPN répond Busy, retry : 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é). SimplePay renvoie l'IPN. La raison est écrite dans le journal.

Le client voit The SimplePay payment could not be started : consultez le champ Log de la page du module. Une mauvaise secret key donne Invalid response signature from SimplePay. Check the secret key of the merchant account. Les erreurs SimplePay sont journalisées avec leurs codes d'erreur.

Après un passage entre sandbox et production : les nouveaux paiements utilisent les comptes du nouveau mode. Les paiements lancés auparavant conservent le compte marchand et le mode avec lesquels ils ont été lancés : leurs IPN, demandes de statut et remboursements utilisent ce compte. Gardez les comptes de l'ancien mode dans les réglages tant que de tels paiements sont ouverts ou peuvent être remboursés.

La commande passe en SimplePay payment on hold après le paiement : lisez les notes du bloc SimplePay payment. Le total ou la devise du panier a été modifié après le lancement du paiement. Traitez la commande ou remboursez le paiement dans l'interface marchand de SimplePay.

Le remboursement échoue : lisez le message du bloc. SimplePay refunds in HUF must be whole amounts. signifie que le montant en HUF comportait des décimales. Si le message indique que le compte marchand de ce paiement n'est pas configuré, saisissez à nouveau le compte (devise et mode) avec lequel le paiement a été effectué. Si SimplePay a remboursé un autre montant, le message vous demande de vérifier le remboursement dans l'interface SimplePay.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox SimplePay Gateway 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 de la passerelle 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 transactions et remboursements SimplePay ainsi que le statut de commande SimplePay 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 leurs identifiants de transaction.

SimplePay est une marque déposée de son propriétaire. Ce module n'est ni affilié à SimplePay ni approuvé par SimplePay.