VibeFox ePay.bg for OpenCart — Aide

Prérequis

OpenCart : 3.0.x (testé sur 3.0.5.0) ou 4.0.2 et ultérieur (testé sur 4.1.0.3).

PHP : 8.0 ou ultérieur.

Devise : lev bulgare (BGN), euro (EUR) ou dollar américain (USD). La commande est débitée dans sa propre devise avec 2 décimales. Lorsque le client paie dans une autre devise, le mode de paiement est masqué.

Compte ePay.bg : vous avez besoin du numéro de client (MIN) et de la clé secrète de votre profil marchand ePay.bg : ceux du mode réel sur www.epay.bg, ceux du test 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 pour un seul domaine.

Installation

Le téléchargement est un fichier ZIP contenant les paquets pour les deux versions d'OpenCart. Décompressez-le sur votre ordinateur. Il contient README.txt, le paquet OpenCart 3 wcp_epaybg_gateway-oc3-(version).ocmod.zip et le paquet OpenCart 4 wcp_epaybg_gateway.ocmod.zip. N'installez que le paquet de votre version d'OpenCart. La clé de licence est la même pour les deux versions.

OpenCart 3

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier wcp_epaybg_gateway-oc3-(version).ocmod.zip. L'extension ne comporte aucune modification OCMOD, donc Extensions > Modifications n'a pas besoin d'être actualisé. Au lieu de l'installateur, vous pouvez copier le contenu du dossier upload de ce paquet dans le dossier racine de votre boutique.

2. Allez dans Extensions > Extensions et choisissez le type Payments. Repérez VibeFox ePay.bg Gateway et cliquez sur Install (le bouton vert +). Votre utilisateur administrateur doit avoir le droit de modifier la liste des extensions de paiement.

3. Cliquez sur Edit (le bouton crayon) pour ouvrir la page des réglages. Collez votre clé de licence VibeFox dans License key, dans le bloc de licence en haut de la page, puis cliquez sur Activate (voir Clé de licence).

4. Saisissez le MIN et la clé secrète de test et/ou du mode réel (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 elle, aucune commande ne reçoit de statut.

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

OpenCart 4

1. Dans l'administration, allez dans Extensions > Installer, cliquez sur Upload et choisissez le fichier wcp_epaybg_gateway.ocmod.zip. Ne renommez pas le fichier : OpenCart 4 tire le code de l'extension du nom du fichier, et un paquet renommé ne fonctionne pas.

2. Le paquet apparaît dans la liste des extensions installées sur la même page. Cliquez sur Install (le bouton vert +) à côté.

3. Allez dans Extensions > Extensions et choisissez le type Payments. Repérez VibeFox ePay.bg Gateway, cliquez sur Install (le bouton vert +), puis sur Edit (le bouton crayon).

4. Saisissez la clé de licence, les identifiants ePay.bg et l'URL de notification comme aux étapes 3 à 6 pour OpenCart 3. La page des réglages et ses champs sont les mêmes dans les deux versions. Seule l'URL de notification diffère (voir Notifications de paiement (IPN)).

Une nouvelle installation démarre avec le mode de paiement désactivé et le mode test activé.

Configuration

Tous les réglages se trouvent sur la page de l'extension : Extensions > Extensions > Payments > VibeFox ePay.bg Gateway > Edit. Les sections sont listées à gauche ; le bouton Save sous la liste enregistre toute la page. Au-dessus des réglages, la page affiche une erreur lorsque la devise par défaut de la boutique n'est ni BGN, ni EUR, ni USD ; un avertissement lorsque le mode de paiement est activé mais que le MIN ou la clé secrète du mode sélectionné est vide (il est alors masqué au moment du 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é. Sans le droit de modifier l'extension, la page affiche les réglages mais ne peut pas les enregistrer.

Lors de l'enregistrement, Title ne doit pas être vide (128 caractères maximum), Sort Order doit être un nombre entier et Total un nombre égal ou supérieur à 0 ; si un champ est incorrect, rien n'est enregistré.

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 au moment du paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : ePay.bg. Obligatoire.

Description : le texte affiché au client à l'étape Confirm Order. Par défaut : Pay securely via ePay.bg with a bank card or your ePay.bg account.

Sort Order : la position d'ePay.bg parmi les modes de paiement proposés au moment du paiement. Laissez vide ou saisissez un nombre entier.

Geo Zone : ne proposer ePay.bg que pour les adresses de facturation situées dans la zone géographique sélectionnée. Par défaut : All zones. Les zones géographiques se configurent dans System > Localisation > Geo Zones.

Total : le total du panier, dans la devise par défaut de la boutique, qu'une commande doit atteindre pour qu'ePay.bg soit proposé. Laissez vide pour proposer ePay.bg quel que soit le total.

Compte ePay.bg

Le numéro de client (MIN) et la clé secrète figurent dans votre profil marchand sur www.epay.bg (mode 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 requêtes sont signées avec les identifiants de test. Par défaut : activé. Tant qu'il est activé, les clients voient Test mode (demo.epay.bg): no real payment is taken. à l'étape Confirm Order.

Test Merchant ID (MIN) : le numéro de 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 de 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 jamais affichées à nouveau. Le champ reste vide et affiche Saved — leave empty to keep it. Saisissez une nouvelle valeur uniquement pour la changer. Pour supprimer une clé enregistrée, cochez Clear the saved key on save sous le champ et cliquez sur Save. Les espaces et les sauts de ligne dans les clés collées sont supprimés à l'enregistrement.

Notifications de paiement (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 mode réel comme en démonstration. Sur OpenCart 3, elle ressemble à https://your-store/index.php?route=extension/payment/wcp_epaybg_gateway/notify, sur OpenCart 4 à https://your-store/index.php?route=extension/wcp_epaybg_gateway/payment/wcp_epaybg_gateway.notify. Elle est construite à partir de l'adresse de la vitrine de votre installation OpenCart. Copiez l'URL exactement telle qu'elle est affichée dans les réglages. Les commandes ne reçoivent un statut que grâce à ces notifications signées ; le client qui revient dans la boutique ne paie pas une commande.

ePay.bg signale 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 ; ainsi, les paiements lancés avant de basculer entre test et réel sont toujours confirmés. Un paiement doit arriver dans le mode où sa demande a été faite ; sinon, la commande passe au statut en attente (on hold). Sans l'URL de notification dans le profil marchand, aucune commande ne reçoit de statut.

Demande de paiement

Invoice Prefix : chiffres uniquement (10 au maximum), placés devant l'identifiant de commande OpenCart 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 qui affiche le préfixe enregistré. Changer le préfixe plus tard ne pose pas de problème : les demandes de paiement en cours sont retrouvées grâce à la facture enregistrée pour chacune. Par défaut : 00001.

Expiration Time : le délai au terme duquel une demande de paiement non payée expire ; ePay.bg la signale alors comme expirée et la commande ne reçoit aucun statut. Choisissez 1, 3, 6, 12, 24, 48 ou 72 heures. L'heure est envoyée à 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 d'ePay.bg, anglais ou bulgare. Par défaut : English.

Commandes

OpenCart crée la commande à l'étape Confirm Order sans statut (une commande manquante). Elle ne reçoit un statut que lorsque ePay.bg signale le paiement. Un paiement refusé, expiré ou abandonné laisse la commande sans statut, et le client peut payer à nouveau. Les champs de statut ci-dessous listent vos statuts de commande OpenCart.

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

Processing status : le statut OpenCart pour Default et Processing. Par défaut : Processing.

Completed status : le statut OpenCart pour Completed. Par défaut : Complete.

On Hold status : le statut OpenCart pour On Hold et pour les paiements qui nécessitent une vérification manuelle : le montant total ou la devise a changé après la demande de paiement, la notification est arrivée dans l'autre mode, ou le statut de la commande a été modifié avant l'arrivée du paiement (par exemple annulée). Une telle commande n'est pas marquée comme payée ; une note explique pourquoi. Par défaut : Pending, car OpenCart n'a pas de statut On hold. Vous pouvez créer votre propre statut dans System > Localisation > Order Statuses et le sélectionner ici.

Avancé

Logging : écrit les demandes de paiement et les notifications dans epay_bp_debug.log.php, dans le dossier des journaux d'OpenCart (storage/logs). Le fichier ne peut pas être ouvert depuis le web et, à 5 Mo, il est déplacé vers epay_bp_debug.old.log.php. 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, même lorsque cette option est désactivée.

Log : affiche la taille et les dernières entrées du journal. Cliquez sur Clear log pour le vider.

Delete Data on Uninstall : lorsqu'il est activé, la désinstallation de l'extension supprime les réglages de la passerelle et le journal. Les enregistrements de paiement et les commandes ePay.bg sont toujours conservés. Par défaut : désactivé.

Import / Export

Export : Download JSON enregistre les réglages dans un fichier JSON. Les clés secrètes ne sont pas exportées.

Import : collez le JSON exporté précédemment et cliquez sur Import pour restaurer les réglages. Les clés secrètes enregistrées sont conservées.

Paiement

À l'étape Payment Method, le client choisit le mode de paiement (par défaut ePay.bg). À l'étape Confirm Order, le client voit votre description ainsi que la mention You will be redirected to ePay.bg to pay with a bank card or your ePay.bg account. OpenCart crée la commande à cette étape, toujours sans statut. Sur OpenCart 4, le client choisit le mode de paiement avec le bouton Choose du bloc du mode de paiement, dans la fenêtre Payment method options, puis clique sur Confirm Order en bas de la page de commande. Lorsque le client clique sur Confirm Order, l'extension l'envoie vers ePay.bg avec une demande de paiement signée pour le total de la commande dans la devise de la commande, avec le numéro de facture et le délai d'expiration. Le paiement apparaît sur ePay.bg sous le libellé Order et le numéro de commande. Sur ePay.bg, le client paie avec une carte bancaire ou un compte ePay.bg.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée payée qu'après confirmation par ePay.bg au moyen de la notification signée. Elle reçoit alors son statut de la manière standard d'OpenCart, avec les e-mails habituels de commande et la mise à jour des stocks. Si la notification est déjà arrivée, le client voit la page de succès de commande d'OpenCart. Sinon, une page Payment confirmation affiche Thank you. Your payment is being confirmed by ePay.bg — your order is confirmed as soon as ePay.bg reports the payment. 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é. Sur OpenCart 4, ces messages s'affichent au-dessus de la page de commande. Une nouvelle tentative pour la même commande utilise le même numéro de facture. OpenCart 3 crée une nouvelle commande chaque fois que l'étape Confirm Order est affichée ; OpenCart 4 met à jour la commande du paiement, de sorte qu'une nouvelle tentative paie la même commande avec une nouvelle demande de paiement ; lorsqu'une autre commande du même panier est déjà payée, le client accède à la page de succès et aucun nouveau paiement n'est lancé.

Sur OpenCart 4, la commande reste à l'étape de paiement jusqu'à l'affichage de la page de succès. Si cette commande a été fermée sans paiement entre-temps (par exemple si vous l'avez annulée), le client est renvoyé à l'étape de paiement avec Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., et le prochain clic sur Confirm Order paie une nouvelle commande du panier. Si cette commande est déjà payée mais que le panier a changé depuis, y compris une nouvelle quantité, le client est renvoyé à l'étape de paiement, et le prochain clic sur Confirm Order paie le nouveau panier avec une nouvelle commande. Une commande payée n'est jamais présentée comme payée pour un autre panier.

Si la commande ne peut pas être payée avec ePay.bg, le client reste à l'étape Confirm Order avec un bref message au-dessus du bouton, 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 de la commande.

La notification fonctionne aussi lorsque la boutique est en mode maintenance, car OpenCart 3 laisse passer les requêtes des extensions de paiement, et l'extension ajoute sur OpenCart 4 une action de démarrage pour cela. Les notifications de paiements déjà lancés sont acceptées même si vous désactivez le mode de paiement.

L'extension ne traite que les paiements uniques sur ePay.bg. Elle ne propose ni remboursements depuis OpenCart, 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 status (missing order) : 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. Dans Sales > Orders, ces commandes ne s'affichent qu'avec le filtre Order Status réglé sur Missing Orders.

Processing, Completed ou On Hold status : le paiement a été confirmé. Le statut suit Order Status After Payment. Une note affiche le numéro de facture, la date du paiement, le STAN et le code BORICA.

Statut On Hold après paiement : le paiement est arrivé, mais pas pour ce que la commande indique maintenant : le montant total ou la devise a changé après la demande de paiement, la notification est arrivée dans l'autre mode (test ou réel) que celui de la demande, ou le mode de paiement de la commande n'est plus ePay.bg. Le paiement n'est pas enregistré comme payé. Il en va de même si vous aviez déjà attribué à la commande un autre statut, par exemple annulée. La note explique la raison. Vérifiez le paiement dans l'espace marchand ePay.bg, puis traitez ou remboursez la commande manuellement.

Si un paiement arrive pour une commande déjà payée, le statut ne change pas, et une note vous invite à vérifier s'il s'agit d'un double paiement dans l'espace marchand ePay.bg. Si le client a payé deux commandes du même panier, la seconde reçoit une note signalant un éventuel double paiement. Un avis tardif de refus ou d'expiration ne modifie jamais une commande payée ; une commande déjà dotée d'un statut reçoit seulement une note.

Les notes sont des entrées de l'History de la commande que le client ne voit pas.

Onglet VibeFox ePay.bg Gateway

Dans Sales > Orders, ouvrez une commande payée avec ePay.bg. En bas de la page de commande, à côté de History et Additional, l'onglet VibeFox ePay.bg Gateway affiche la facture, l'environnement (test ou réel) avec un libellé Test mode pour les paiements de test, le montant demandé et la devise, l'état de la demande de paiement, le résultat de la notification, la date du paiement, le STAN, le code BORICA et les ePay.bg notes de la commande. L'onglet est en lecture seule et s'affiche aux utilisateurs qui ont accès à l'extension.

Remboursements

Les remboursements depuis OpenCart ne sont pas disponibles, car l'API WEB d'ePay.bg ne dispose d'aucun appel de remboursement. Remboursez le paiement dans l'espace marchand ePay.bg, puis mettez à jour manuellement le statut de la commande dans OpenCart. Les retours de produits dans Sales > Returns ne renvoient pas d'argent via ePay.bg.

Clé de licence

L'extension 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 Extensions > Extensions > Payments > VibeFox ePay.bg Gateway > Edit, 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) 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 se trouvent la ligne Product: opencart-payment-epaybg et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les utilisateurs administrateurs disposant du droit Modify sur l'extension peuvent modifier la clé. Les textes du bloc suivent la langue de l'administration (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, l'extension continue de fonctionner avec le dernier statut connu.

Une clé fonctionne pour un seul domaine : l'adresse de la boutique issue de la configuration d'OpenCart. 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, ePay.bg 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. Un utilisateur administrateur connecté à l'administration dans le même navigateur voit encore le mode de paiement dans la boutique, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Sur OpenCart 4, cet aperçu n'est pas disponible : la boutique ne voit pas la connexion à l'administration, donc sans clé active le mode de paiement est masqué pour tout le monde. Après avoir ouvert une fois la page Edit, un rappel apparaît sur le Dashboard de l'administration. Fermez-le avec × pour le masquer pendant 7 jours. Les commandes existantes ne sont pas affecté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 lorsque vous ouvrez le Dashboard ou la page Edit de l'administration : 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 de l'extension supprime toujours la clé de licence et le statut de licence.

Dépannage

ePay.bg n'apparaît pas au moment du 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 le client paie en BGN, EUR ou USD. La page des réglages affiche un avertissement lorsque les identifiants manquent. Vérifiez aussi que l'adresse de facturation se trouve dans la Geo Zone sélectionnée et que la commande atteint le Total défini dans les réglages.

Le paiement a été effectué, mais la commande reste sans statut : la commande ne reçoit son statut qu'à partir de la notification d'ePay.bg. Vérifiez que l'URL de notification est saisie dans le profil marchand ePay.bg du mode que vous utilisez (démonstration ou réel), exactement comme elle apparaît sous Notification URL, et que la clé secrète de ce mode est correcte. Regardez le champ Log sur la page de l'extension ; 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 réessaie, donc la commande recevra son statut dès que la clé sera 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. Donnez à chaque boutique son propre Invoice Prefix.

La notification répond STATUS=ERR : une erreur temporaire, par exemple deux notifications pour la même commande au même moment, ou le statut de la commande n'a pas pu être défini. ePay.bg renvoie la notification. La raison figure dans le journal.

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

Le client voit This payment method is not available. Please reload the checkout page. : la session de paiement ne correspond plus à la commande, ou le mode de paiement a été désactivé entre-temps. Le client recharge la page de paiement.

Le client voit This order has nothing to pay. : le total de la commande est nul, il n'y a donc rien à envoyer à ePay.bg.

La commande est au statut On Hold après paiement : lisez les notes de l'onglet VibeFox ePay.bg Gateway (voir Statuts de commande), vérifiez le paiement dans l'espace marchand ePay.bg, puis traitez la commande ou remboursez le paiement là-bas.

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

Pour les développeurs : avant l'envoi du formulaire de paiement à ePay.bg, l'extension déclenche l'événement OpenCart epay_bp_form_fields avec les champs du formulaire et la commande, par exemple pour utiliser la page de paiement par carte directe (PAGE=credit_paydirect) ; les données signées et la somme de contrôle ne peuvent pas être modifiées par son intermédiaire.

Désinstallation

Allez dans Extensions > Extensions, choisissez le type Payments et cliquez sur Uninstall (le bouton rouge −) à côté de VibeFox ePay.bg Gateway. La clé de licence et le statut de licence de cette extension sont toujours supprimés. OpenCart supprime toujours ses propres réglages de l'extension : Enable/Disable, Sort Order, Geo Zone, Total et les statuts de commande de la section Orders, qui reviennent à leurs valeurs par défaut lors d'une réinstallation. Sur OpenCart 4, l'événement de l'extension (le message du paiement) et son action de démarrage, qui laisse passer la notification en mode maintenance, sont aussi supprimés. Si Delete Data on Uninstall est activé, les autres réglages de la passerelle (titre, description, mode test, MIN et clés secrètes, demande de paiement, statut après paiement, journalisation) et le journal sont supprimés. S'il est désactivé, ils sont conservés pour une réinstallation ultérieure. Les enregistrements de paiement d'ePay.bg sont toujours conservés, de sorte qu'un paiement lancé avant une réinstallation est toujours confirmé. Les commandes existantes conservent leurs notes de paiement.

Sur OpenCart 4, pour supprimer aussi les fichiers de l'extension, allez dans Extensions > Installer après la désinstallation et cliquez sur Uninstall (le bouton orange −) à côté de VibeFox ePay.bg Gateway dans la liste des extensions installées, puis sur Delete (le bouton corbeille rouge) pour supprimer le paquet envoyé.

ePay.bg est une marque déposée de son titulaire. Cette extension n'est ni affiliée à ePay.bg ni approuvée par elle.