VibeFox ePay.bg for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

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

Devise : lev bulgare (BGN), euro (EUR) ou dollar américain (USD). Le panier est débité dans sa propre devise avec 2 décimales. Pour les paniers dans d'autres devises, le mode de paiement est masqué à l'étape de paiement.

Compte ePay.bg : vous avez besoin du numéro client (MIN) et de la clé secrète de votre profil marchand ePay.bg : les réels sur www.epay.bg, les tests sur demo.epay.bg (un compte de test s'enregistre séparément). Vous devez aussi saisir l'URL de notification de votre boutique dans le profil marchand.

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

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

4. Saisissez le MIN et la clé secrète de test et/ou de production (voir Configuration).

5. Copiez l'URL affichée dans la section Payment notifications (IPN) dans le champ URL for receiving notifications du profil marchand ePay.bg, dans le profil de démonstration comme dans le profil réel. Sans cela, aucune commande n'est créée.

6. Activez Enable/Disable et cliquez sur Save. Passez une commande test en mode test, puis désactivez Test Mode.

À l'installation, le module crée le statut de commande ePay.bg payment on hold. PrestaShop propose le nouveau module de paiement pour toutes les devises, tous les pays et tous les groupes de clients. Vous pouvez les restreindre dans Payment > Preferences.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox ePay.bg Gateway > Configure. Chaque bouton Save enregistre la page entière. Au-dessus des champs, la page affiche une erreur si la devise par défaut de la boutique n'est ni BGN, ni EUR, ni USD ; un avertissement si la passerelle est activée mais que le MIN ou la clé secrète du mode sélectionné est vide (elle est alors masquée à l'étape de paiement, et l'enregistrement affiche le même avertissement) ; et Test mode is on: payments go to demo.epay.bg and no real money is charged. tant que le mode test est activé.

ePay.bg

Enable/Disable : Enable ePay.bg Payment 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 à l'étape de paiement. C'est aussi le nom du mode de paiement enregistré sur la commande. Par défaut : ePay.bg. Obligatoire.

Description : le texte affiché sous le mode de paiement à l'étape de paiement. Par défaut : Pay securely via ePay.bg with a bank card or your ePay.bg account.

Compte ePay.bg

Le numéro client (MIN) et la clé secrète figurent dans votre profil marchand sur www.epay.bg (réel) et demo.epay.bg (compte de test, enregistré séparément).

Test Mode : active le mode test. Les clients sont envoyés vers l'environnement de démonstration d'ePay.bg et les demandes sont signées avec les identifiants de test. Par défaut : activé.

Test Merchant ID (MIN) : le numéro client (MIN) de votre compte marchand demo.epay.bg.

Test Secret Key : la clé secrète de votre compte marchand demo.epay.bg (64 caractères).

Live Merchant ID (MIN) : le numéro client (MIN) de votre compte marchand www.epay.bg.

Live Secret Key : la clé secrète de votre compte marchand www.epay.bg (64 caractères), utilisée pour la signature HMAC-SHA1.

Les clés secrètes enregistrées ne sont plus jamais affichées. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la modifier. Les espaces et les sauts de ligne des clés collées sont supprimés à l'enregistrement.

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

Payment notifications (IPN)

La notification indique à votre boutique qu'une demande de paiement a été payée, refusée ou a expiré. Le champ Notification URL affiche l'URL à saisir comme URL for receiving notifications dans le profil marchand ePay.bg, en réel comme en test. Avec les URL réécrites, elle ressemble à https://your-shop/module/wcp_epaybg_gateway/notify, éventuellement avec un code de langue comme /en/. Copiez l'URL exactement telle qu'affichée dans les réglages. Les commandes ne sont créées que par ces notifications signées ; le retour du client dans la boutique ne crée ni ne paie de commande.

ePay.bg communique ces résultats pour chaque facture :

Les notifications sans somme de contrôle valide sont rejetées, et ePay.bg continue de les envoyer. La somme de contrôle est vérifiée avec la clé secrète de chaque mode qui en possède une, de sorte que les paiements commencés avant le passage du test au réel (ou inversement) sont toujours confirmés. Un paiement doit arriver dans le mode où sa demande a été faite ; sinon, la commande passe à ePay.bg payment on hold. Sans l'URL de notification dans le profil marchand, aucune commande n'est créée.

Demande de paiement

Invoice Prefix : chiffres uniquement (jusqu'à 10), placés devant l'ID du panier pour former le numéro de facture ePay.bg, par exemple 00001 + 123 = 00001123. Utilisez des préfixes différents pour des boutiques différentes sur un même compte ePay.bg. Les autres caractères sont supprimés à l'enregistrement, avec un avertissement. Modifier le préfixe plus tard ne pose pas de problème : les demandes de paiement ouvertes sont retrouvées grâce à la facture enregistrée pour chacune. Par défaut : 00001.

Expiration Time : le délai au-delà duquel une demande de paiement non payée expire ; ePay.bg la signale alors comme expirée, et aucune commande n'est créée. Choisissez 1, 3, 6, 12, 24, 48 ou 72 heures. L'heure est transmise à l'heure bulgare, quel que soit le fuseau horaire de votre boutique. Par défaut : 24 heures.

Language : la langue de la page de paiement ePay.bg, anglais ou bulgare. Par défaut : anglais.

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

Advanced

Logging : enregistre les demandes de paiement et les notifications dans logs/epay_bp_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les clés secrètes et les données de carte ne sont pas journalisées. Par défaut : désactivé. Les erreurs sont toujours journalisées, y compris lorsqu'il est 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 enregistrements de paiements ePay.bg, le statut de commande ePay.bg payment on hold et les commandes sont toujours conservés. Par défaut : désactivé.

Paiement

À l'étape de paiement, le client choisit le mode de paiement (par défaut ePay.bg) et valide. Le client voit Redirecting to ePay.bg for payment... et est redirigé vers ePay.bg avec une demande de paiement signée pour le total du panier dans la devise du panier, avec le numéro de facture et le délai d'expiration. Le paiement apparaît sur ePay.bg sous le nom Cart et le numéro du panier. La page comporte aussi un bouton Pay via ePay.bg, au cas où la redirection ne démarrerait pas, et un bouton Cancel. Sur ePay.bg, le client paie avec une carte bancaire ou un compte ePay.bg. Aucune commande n'existe encore à ce stade.

Après le paiement, le client revient dans votre boutique. La commande n'est créée que lorsque la notification signée d'ePay.bg arrive. Si elle est déjà arrivée, le client voit la page standard de confirmation de commande. Sinon, une page Payment confirmation affiche Thank you. Your payment is being confirmed by ePay.bg — your order will be created as soon as ePay.bg confirms it, and you will receive an e-mail. avec les boutons Check again et Back to checkout.

Si le client annule sur ePay.bg, il revient à l'étape de paiement avec le message The ePay.bg payment was cancelled. You can try again or choose another payment method. Si ePay.bg a signalé la demande comme refusée ou expirée, le message est The payment was not completed. You can try again or choose another payment method. Le panier est conservé. Une nouvelle tentative pour le même panier utilise le même numéro de facture.

Si le panier ne peut pas être payé avec ePay.bg, le client reste à l'étape de paiement avec un court message, par exemple ePay.bg payments are temporarily unavailable. Please choose another payment method. ou indiquant qu'ePay.bg n'accepte pas les paiements dans la devise du panier.

La notification fonctionne pendant que la boutique est en mode maintenance et n'est pas bloquée par la restriction par pays de votre boutique.

Le module n'accepte que les paiements uniques sur ePay.bg. Il ne propose ni remboursements depuis PrestaShop, ni cartes enregistrées, ni abonnements ou paiements récurrents, ni codes de paiement en espèces EasyPay ou B-Pay.

Commandes

Statuts de commande

No order yet : le client a été envoyé vers ePay.bg et n'a pas payé, la notification n'est pas encore arrivée, ou ePay.bg a signalé la demande comme refusée ou expirée. Seul le panier existe.

Payment accepted, Delivered or ePay.bg payment on hold : le paiement a été confirmé. Le statut suit Order Status After Payment. Le paiement est enregistré avec le STAN comme ID de transaction (ou le numéro de facture s'il n'y a pas de STAN), et une note indique le numéro de facture, la date du paiement, le STAN et le code BORICA.

ePay.bg payment on hold after payment : le paiement est arrivé, mais ne correspond pas à ce qu'indique maintenant le panier : le total ou la devise du panier a été modifié après la demande de paiement, ou la notification est arrivée dans un autre mode (test ou réel) que celui de la demande. Le paiement n'est pas enregistré comme payé. Il en va de même lorsque le panier a déjà une commande impayée, par exemple une commande annulée ou passée avec un autre mode de paiement. La note explique la raison. Vérifiez le paiement dans le panneau marchand d'ePay.bg, puis traitez ou remboursez la commande manuellement.

Si un paiement arrive pour une commande déjà payée ou remboursée, le statut n'est pas modifié et une note vous demande de vérifier un double paiement dans le panneau marchand d'ePay.bg. Un avis tardif de refus ou d'expiration ne modifie jamais une commande payée.

Bloc de paiement ePay.bg

La page de commande affiche un bloc ePay.bg payment avec la facture, le montant et la devise demandés, le résultat de la notification, la date du paiement, le STAN, le code BORICA, un badge Test mode pour les paiements test et les ePay.bg notes de la commande.

Remboursements

Les remboursements depuis PrestaShop ne sont pas disponibles, car l'API WEB d'ePay.bg ne dispose d'aucun appel de remboursement. Remboursez le paiement dans le panneau marchand d'ePay.bg et mettez à jour la commande dans PrestaShop manuellement.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox ePay.bg Gateway est le premier bloc de Modules > Module Manager > VibeFox ePay.bg 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 active 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-epaybg 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-le dans votre compte vibefox.net.

Sans clé active, ePay.bg n'est pas affiché aux clients à l'étape de 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 de 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 à l'étape de paiement. Un rappel apparaît dans Modules > Module Manager, sous l'onglet Alerts. Les commandes existantes ne sont pas affectées : les paiements déjà commencés sont toujours confirmés.

Lorsqu'une licence expire, le module continue de fonctionner, mais les mises à jour et l'assistance 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

ePay.bg n'apparaît pas à l'étape de paiement : vérifiez que la licence est active, que Enable/Disable est activé, que le MIN et la clé secrète du mode sélectionné sont renseignés et que la devise du panier est BGN, EUR ou USD. La page des réglages affiche un avertissement lorsque les identifiants 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.

Le paiement a été effectué, mais aucune commande n'a été créée : la commande n'est créée que par la notification d'ePay.bg. Vérifiez que l'URL de notification est saisie dans le profil marchand ePay.bg du mode utilisé (démo ou réel), exactement comme affiché dans Notification URL, et que la clé secrète de ce mode est correcte. Consultez le champ Log sur la page du module ; activez Logging pour voir chaque notification.

La notification répond ERR=Not valid CHECKSUM : aucune clé secrète enregistrée ne correspond au profil marchand qui a envoyé la notification. ePay.bg continue de réessayer, donc la commande est créée dès que la clé est correcte.

La notification répond ERR=Not configured : aucune clé secrète n'est enregistrée. Saisissez-la.

La notification répond STATUS=NO pour une facture : la facture n'a pas été émise par cette boutique, par exemple par une autre boutique sur le même compte ePay.bg. Attribuez à chaque boutique son propre Invoice Prefix.

La notification répond STATUS=ERR : une erreur temporaire, par exemple deux notifications pour le même panier au même moment, ou la commande n'a pas pu être créée (par exemple, le module est désactivé). ePay.bg renvoie la notification. La raison figure dans le journal.

L'URL de notification affiche ERR=Method not allowed in the browser : c'est normal. L'URL n'accepte que les requêtes provenant d'ePay.bg.

La commande est ePay.bg payment on hold après paiement : lisez les notes du bloc ePay.bg payment (voir Statuts de commande), vérifiez le paiement dans le panneau marchand d'ePay.bg, puis traitez la commande ou remboursez le paiement à cet endroit.

Le préfixe de facture a été modifié à l'enregistrement : le préfixe ne peut contenir que des chiffres, jusqu'à 10. Les autres caractères sont supprimés.

Pour les développeurs, le readme mentionne le hook actionEpayBpFormFields (le filtre epay_bp_form_fields de la version WooCommerce), par exemple pour utiliser la page de carte directe (PAGE=credit_paydirect).

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox ePay.bg 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 future réinstallation. Les enregistrements de paiements ePay.bg et le statut de commande ePay.bg payment on hold sont toujours conservés, de sorte qu'un paiement commencé avant une réinstallation est toujours confirmé. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

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