VibeFox ePay.bg for WooCommerce — Aide

Prérequis

WordPress : 6.0 ou ultérieur.

WooCommerce : 7.0 ou ultérieur, installé et activé.

PHP : 8.0 ou ultérieur.

Devise de la boutique : lev bulgare (BGN), euro (EUR) ou dollar américain (USD). La commande est facturée dans sa propre devise avec 2 décimales. Pour les autres devises, le mode de paiement est masqué au paiement.

Compte ePay.bg : vous avez besoin du numéro client (MIN) et de la clé secrète de votre profil marchand ePay.bg : ceux de production sur www.epay.bg, ceux de test sur demo.epay.bg (un compte de test est enregistré 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 WordPress, allez dans Plugins > Add New > Upload Plugin, choisissez le fichier ZIP de l'extension et cliquez sur Install Now. Vous pouvez aussi envoyer le dossier wcp_epaybg_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate. WooCommerce doit être activé.

3. Ouvrez les réglages : WooCommerce > Settings > Payments > ePay.bg > Manage, ou cliquez sur Settings sous le nom de l'extension dans la page des extensions.

4. Saisissez votre clé de licence VibeFox dans le bloc de licence en haut de la page et cliquez sur Activate.

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

6. Copiez l'URL de notification affichée dans la section Payment notifications (IPN) dans le champ URL for receiving notifications du profil marchand ePay.bg, à la fois dans le profil demo et dans le profil de production. Sans elle, les commandes restent en attente de paiement.

7. Activez Enable/Disable. Passez une commande de test en mode test, puis décochez Test Mode.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > ePay.bg. Au-dessus des champs, la page affiche une erreur lorsque la devise de la boutique n'est pas BGN, EUR ou USD, un avertissement lorsque 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 au paiement, et l'enregistrement affiche la même erreur), et Test mode is on: payments go to demo.epay.bg and no real money is charged. tant que le mode test est activé. Dans la liste des modes de paiement, ePay.bg est signalé comme à configurer tant que les identifiants du mode sélectionné ne sont pas saisis.

Général

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 les clients voient au paiement. Par défaut : ePay.bg.

Description: le texte affiché sous le mode de paiement au 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 sont affichés dans votre profil marchand sur www.epay.bg (production) et demo.epay.bg (compte de test, enregistré séparément). Les espaces et les sauts de ligne des clés secrètes collées sont supprimés à l'enregistrement.

Test Mode: Enable test mode (use demo.epay.bg and the test credentials). Lorsqu'il est activé, 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.

Si vous mettez à jour depuis la version 1.0, l'unique jeu d'identifiants de cette version est déplacé vers les champs de test lorsque le mode test était activé.

Notifications de paiement (IPN)

La notification indique à votre boutique qu'une demande de paiement a été payée, refusée ou a expiré. Cette section affiche l'URL de notification. Elle se présente ainsi : https://your-site/wc-api/epaybg_payment_callback/. Saisissez-la comme URL for receiving notifications dans le profil marchand ePay.bg, en production et en test. Les commandes ne sont marquées comme payées que par ces notifications signées ; le retour du client dans la boutique ne marque pas une commande comme payée.

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

PAID: le client a payé. La commande est marquée comme payée.

DENIED: le paiement a été refusé. La commande impayée est annulée.

EXPIRED: la demande de paiement a expiré sans être payée. La commande impayée est annulée.

Chaque notification est vérifiée avec la clé secrète du mode sélectionné. Les notifications sans somme de contrôle valide sont rejetées, et ePay.bg continue de les envoyer. Sans l'URL de notification dans le profil marchand, aucune commande n'est marquée comme payée.

Demande de paiement

Invoice Prefix: uniquement des chiffres (jusqu'à 10), placés devant l'ID de commande 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. Modifier le préfixe plus tard est sans risque : les commandes en attente sont retrouvées grâce à la facture enregistrée sur la commande. Par défaut : 00001.

Expiration Time: le délai après lequel une demande de paiement impayée expire ; ePay.bg la signale alors comme expirée et la commande en attente est annulée. Choisissez 1, 3, 6, 12, 24, 48 ou 72 heures. L'heure est envoyée en heure bulgare, quel que soit le fuseau horaire de votre site. 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 commande appliqué après un paiement réussi. Le statut est appliqué immédiatement, sans second changement de statut.

Default (WooCommerce decides): En cours, ou Terminée pour les commandes contenant uniquement des produits virtuels téléchargeables (par défaut).

Processing: toute commande payée passe en En cours.

Completed: toute commande payée passe en Terminée.

On Hold: toute commande payée attend votre examen manuel.

Avancé

Logging: Enable logging écrit les demandes de paiement et les notifications dans WooCommerce > Status > Logs, source wcp_epaybg_gateway, sans clés secrètes ni données de carte. Par défaut : désactivé.

Delete Data on Uninstall: Remove all plugin data when uninstalled. Si cette option est cochée, les réglages de la passerelle, les données ePay.bg enregistrées sur les commandes et les journaux de l'extension sont supprimés lors de la désinstallation de l'extension. Par défaut : désactivé.

Paiement

Le client choisit le mode de paiement (par défaut ePay.bg) et passe la commande. Il voit Redirecting to ePay.bg for payment... et est envoyé 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. La page comporte aussi un bouton Pay via ePay.bg au cas où la redirection ne démarrerait pas, et un bouton Cancel order. Sur ePay.bg, le client paie avec une carte bancaire ou un compte ePay.bg.

Après le paiement, le client revient sur la page de commande reçue de votre boutique. La commande n'est marquée comme payée que lorsque la notification signée d'ePay.bg arrive. Le panier n'est vidé que sur la page de commande reçue.

Si le client annule sur ePay.bg, la commande est annulée de la manière standard de WooCommerce et le panier est conservé, de sorte que le client peut choisir un autre mode de paiement.

Si la commande ne peut pas être payée avec ePay.bg, le client voit un court message, par exemple ePay.bg payments are temporarily unavailable. Please choose another payment method. ou l'indication qu'ePay.bg n'accepte pas les paiements dans la devise de la commande.

Le mode de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est compatible avec le stockage des commandes haute performance (HPOS) de WooCommerce.

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

Commandes

Statuts de commande

Pending payment: le client a été envoyé vers ePay.bg et n'a pas encore payé, ou la notification n'est pas encore arrivée. La note de commande indique Awaiting ePay.bg payment.

Processing, Completed or On Hold: le paiement a été confirmé. Le statut suit le réglage Order Status After Payment. La note de commande indique le numéro de facture, la date du paiement, le STAN et le code BORICA. L'ID de transaction est le STAN (ou le numéro de facture s'il n'y a pas de STAN).

On hold after payment: le paiement est arrivé, mais pas pour ce que la commande indique maintenant : le total ou la devise a été modifié après la demande de paiement, la demande a été faite dans l'autre mode ou la passerelle a ensuite été basculée entre test et production, le mode de paiement de la commande a été changé, ou la commande avait été annulée auparavant. La note de commande en explique la raison. Vérifiez le paiement dans le panneau marchand ePay.bg et terminez ou remboursez la commande manuellement.

Cancelled: ePay.bg a signalé la demande de paiement comme refusée ou expirée, ou le client a annulé sur ePay.bg. WooCommerce rétablit le stock. Une commande annulée ne peut pas être payée à nouveau, car le numéro de facture ePay.bg est le préfixe suivi de l'ID de commande. Le client passe une nouvelle commande.

Un avis tardif de refus ou d'expiration ne modifie jamais une commande payée. 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 l'absence de double paiement dans le panneau marchand ePay.bg.

Remboursements

Les remboursements depuis WooCommerce ne sont pas disponibles, car l'API WEB d'ePay.bg n'a pas d'appel de remboursement. Remboursez le paiement dans le panneau marchand ePay.bg et enregistrez le remboursement manuellement dans WooCommerce.

Clé de licence

L'extension fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence se trouve en haut de WooCommerce > Settings > Payments > ePay.bg. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche l'état, par exemple la date jusqu'à laquelle la licence est active et votre domaine. Utilisez Check now pour revérifier l'état, Change key pour saisir une autre clé et Remove key pour la retirer de ce site. Le lien Manage licenses and domains in your account ouvre votre compte vibefox.net.

Une clé fonctionne sur un seul domaine. Retirer la clé d'un site 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 paiement. Si un paiement est tout de même lancé, le client voit This payment method is not available. Please choose another one. Les gestionnaires de boutique connectés voient toujours le mode de paiement, marqué (unlicensed — visible to admins only), afin que vous puissiez configurer et tester l'extension avant d'acheter une clé. Un rappel apparaît sur la page des extensions et sur les pages WooCommerce. 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 l'assistance nécessitent un renouvellement. L'état est revérifié automatiquement en arrière-plan.

Dépannage

ePay.bg n'apparaît pas au 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 de la boutique est BGN, EUR ou USD. La page de réglages affiche un avertissement dans chacun de ces cas.

Le paiement est passé, mais la commande reste en attente de paiement : la commande n'est marquée comme payé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 que vous utilisez (demo ou production) et que la clé secrète du mode actif est correcte. Activez Logging et consultez WooCommerce > Status > Logs, source wcp_epaybg_gateway.

La notification répond ERR=Not valid CHECKSUM : la clé secrète des réglages ne correspond pas au profil marchand qui a envoyé la notification. Les notifications sont vérifiées avec la clé du mode actuellement sélectionné, puis avec la clé de l'autre mode, de sorte que les demandes de paiement faites avant le changement de mode sont toujours acceptées. ePay.bg continue de réessayer, la commande est donc mise à jour dès que la clé est correcte.

La notification répond ERR=Not configured : la clé secrète du mode sélectionné est vide. Saisissez-la.

La notification répond STATUS=NO pour une facture : la facture n'appartient pas à une commande ePay.bg de cette boutique, par exemple parce qu'elle a été émise 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. ePay.bg renvoie la notification.

La commande est en attente après le paiement : lisez la note de commande. Le total ou la devise a changé après la demande de paiement, la demande a été faite dans l'autre mode ou le mode a été basculé ensuite, le mode de paiement a changé ou la commande avait été annulée. Vérifiez le paiement dans le panneau marchand ePay.bg.

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.

Le bloc de licence affiche une erreur : suivez le message du bloc. Par exemple, si la clé est déjà utilisée sur un autre domaine, libérez un emplacement dans votre compte vibefox.net et cliquez sur Check now. Si l'adresse du site a changé, cliquez sur Check now pour activer la clé pour le nouveau domaine. Si le serveur de licences est injoignable, l'extension continue de fonctionner sur le dernier état connu.

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

Désinstallation

Désactiver l'extension conserve toutes les données. Pour la supprimer, désactivez-la puis supprimez-la sur la page Plugins. La clé de licence et l'état de la licence de cette extension sont toujours supprimés. Les réglages de la passerelle, les données ePay.bg enregistrées sur les commandes et les journaux ne sont supprimés que si Delete Data on Uninstall était activé. Sinon, ils sont conservés pour une réinstallation ultérieure. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

ePay.bg est une marque de son propriétaire respectif. Cette extension n'est ni affiliée à ePay.bg ni approuvée par ePay.bg.