VibeFox Przelewy24 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 : le panier doit être en PLN, EUR, GBP ou CZK. Dans les autres devises, le moyen de paiement est masqué sur le tunnel de commande. Le panier est débité dans sa propre devise ; le module ne convertit pas les devises.

Compte Przelewy24 : vous avez besoin d'un compte marchand Przelewy24 et de ses données API : le Merchant ID, la clé API (appelée report key dans le panneau Przelewy24), la clé CRC et, si votre boutique possède son propre identifiant, le POS ID (Shop ID). Vous les trouvez dans le panneau marchand Przelewy24 sur panel.przelewy24.pl, sous My data > API data and configuration. Les clés sandbox proviennent d'un compte sandbox distinct, sur sandbox.przelewy24.pl/panel. Rien d'autre n'est à configurer dans le panneau Przelewy24 : le module envoie son URL de notification avec chaque paiement. Votre boutique doit être accessible depuis Internet, car Przelewy24 y envoie les notifications de paiement.

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 VibeFox Przelewy24 Payment plus tard dans la liste des modules et cliquez sur Configure.

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

4. Saisissez les clés sandbox (Merchant ID, clé API, clé CRC ; le POS ID uniquement s'il diffère du Merchant ID), activez Enable/Disable, cliquez sur Save et effectuez un paiement test en mode sandbox.

5. Saisissez les clés live, désactivez Test Mode et cliquez sur Save pour accepter de vrais paiements.

À l'installation, le module crée le statut de commande Przelewy24 payment on hold. PrestaShop propose ensuite 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 Przelewy24 Payment > Configure. Chaque section a son propre bouton Save, qui enregistre toute la page. Au-dessus des champs, la page affiche des avertissements lorsque quelque chose manque. Tant que le sandbox est activé : Sandbox (test) mode is on: payments go to the Przelewy24 sandbox and no real money is charged. Do not ship orders paid in test mode. Lorsque les clés du mode actuel sont incomplètes : Enter the Sandbox Merchant ID, API key and CRC key - until then Przelewy24 is not shown at checkout. (ou la même chose pour les clés Live). Lorsque Przelewy24 n'accepte pas la devise par défaut de votre boutique, l'avertissement indique la devise et celles qui sont prises en charge. Après l'enregistrement, les avertissements suivent immédiatement le nouveau mode et les nouvelles clés. Les espaces et les sauts de ligne copiés avec les clés depuis le panneau Przelewy24 sont supprimés à l'enregistrement.

Przelewy24

Enable/Disable : Enable Przelewy24 Payment active ou désactive le moyen de paiement. Par défaut : désactivé.

Title : le nom du moyen de paiement que voient les clients sur le tunnel de commande. C'est aussi le nom du moyen de paiement enregistré dans la commande. Par défaut : Przelewy24. Obligatoire : si vous enregistrez avec un titre vide, Enter a title for the payment method. s'affiche.

Description : le texte affiché sous le moyen de paiement sur le tunnel de commande. Par défaut : Pay with BLIK, online bank transfer or card via Przelewy24.

Identifiants API

La section explique où trouver les clés (My data > API data and configuration dans le panneau marchand Przelewy24) et renvoie vers panel.przelewy24.pl et sandbox.przelewy24.pl/panel.

Test Mode : utilise le sandbox de Przelewy24 (sandbox.przelewy24.pl) et les clés Sandbox. Aucun argent réel n'est débité. Désactivez-le pour accepter de vrais paiements sur secure.przelewy24.pl avec les clés Live. Par défaut : activé. Tant qu'il est activé, les clients voient Sandbox mode - no real money is charged sous le moyen de paiement.

Clés Live

Live Merchant ID : votre identifiant marchand Przelewy24, chiffres uniquement.

Live POS ID (optional) : le Shop ID (posId). Laissez vide s'il est identique au Merchant ID.

Live API key (report key) : la clé API du panneau Przelewy24. Elle sert à l'authentification API.

Live CRC key : sert à signer les requêtes envoyées à Przelewy24 et à vérifier la signature des notifications de Przelewy24.

Clés Sandbox

Sandbox Merchant ID : le Merchant ID de votre compte sandbox Przelewy24.

Sandbox POS ID (optional) : le Shop ID (posId) du compte sandbox. Laissez vide s'il est identique au Merchant ID.

Sandbox API key (report key) : la clé API du compte sandbox.

Sandbox CRC key : la clé CRC du compte sandbox, utilisée pour signer les requêtes et vérifier les notifications sandbox.

Les clés API et CRC enregistrées ne sont jamais réaffichées. Le champ reste vide et affiche Saved - leave empty to keep it. Ne saisissez une nouvelle valeur que si vous voulez la modifier.

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

Les clés Live et sandbox sont différentes. Le Merchant ID et le POS ID ne doivent contenir que des chiffres ; tant que le Merchant ID, la clé API et la clé CRC du mode actuel ne sont pas saisis, le moyen de paiement n'est pas affiché sur le tunnel de commande. Un paiement lancé dans un mode est toujours vérifié et remboursé avec les clés de ce mode, même après un changement ; conservez donc les clés de l'ancien mode tant que ses paiements sont en cours ou peuvent être remboursés.

Notifications de paiement

Notification URL : l'adresse qui reçoit les notifications de paiement de Przelewy24. Avec des URL conviviales, elle ressemble à https://your-shop/module/wcp_przelewy24_payment/notify, éventuellement avec un code de langue comme /en/. Le module envoie cette URL à Przelewy24 avec chaque paiement et chaque remboursement ; rien n'est donc à configurer dans le panneau Przelewy24. L'URL doit être accessible depuis Internet : aucun pare-feu ni authentification HTTP ne doit la précéder. Elle reste active lorsque la boutique est en mode maintenance et n'est pas bloquée par la restriction géographique de votre boutique. Sans notification, un paiement est tout de même confirmé lorsque le client revient sur la boutique (voir Tunnel de commande) ; si le client ne revient pas, aucune commande n'est créée.

Avancé

Debug Log : écrit les événements techniques (numéros de panier, identifiants de transaction P24, erreurs) dans logs/wc_p24_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs et avertissements, comme les notifications rejetées ou une vérification ou un remboursement échoué, sont toujours journalisés ; activez l'interrupteur pour journaliser aussi chaque étape. Les clés, le contenu des requêtes et les données personnelles ne sont jamais journalisés. 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 : si activé, la désinstallation du module supprime ses réglages et le journal. Les commandes et leurs données de paiement Przelewy24 ne sont jamais supprimées. Par défaut : désactivé.

Tunnel de commande

À l'étape de paiement, le client choisit le moyen de paiement (par défaut Przelewy24, avec le logo P24) et confirme la commande. Le module enregistre une transaction Przelewy24 pour le total du panier dans la devise du panier, avec l'e-mail, le nom et le pays de facturation du client, et la description Cart # avec le numéro de panier et le nom de votre boutique. Chaque tentative de paiement reçoit son propre identifiant de session. Le client est redirigé vers la page de paiement de Przelewy24 et paie avec BLIK, un virement bancaire en ligne, une carte ou un autre moyen activé pour votre compte Przelewy24. La page de paiement s'affiche dans la langue du panier du client si Przelewy24 la prend en charge, sinon en anglais. Aucune commande n'existe encore à ce stade.

La commande n'est marquée payée qu'après confirmation de Przelewy24. Przelewy24 envoie à votre boutique une notification signée. Le module vérifie la signature avec la clé CRC, le Merchant ID et le POS ID ; que la session a été enregistrée pour ce panier et dans le même mode ; et que le montant et la devise correspondent à la tentative de paiement et au total actuel du panier. Ce n'est qu'alors qu'il vérifie la transaction auprès de Przelewy24 (Przelewy24 ne crédite que les paiements vérifiés) et crée la commande en Payment accepted. Les webhooks sans signature valide sont rejetés.

Après le paiement, le client revient sur votre boutique. Si la notification n'est pas encore arrivée, le module demande à Przelewy24 le statut de la transaction par une requête authentifiée de serveur à serveur (au maximum une fois toutes les 10 secondes par panier) et applique les mêmes contrôles. La page de retour seule ne marque jamais une commande comme payée. Lorsque le paiement est confirmé, le client voit la page standard de confirmation de commande. Tant qu'il n'est pas confirmé, une page Payment confirmation affiche We have not received the payment confirmation from Przelewy24 yet. If you have paid, it will be confirmed in a few minutes. If the payment was interrupted, you can try again: avec un bouton Check again et un bouton Pay again qui ouvre le tunnel de commande. Le panier est conservé, et un paiement effectué plus tard sur une ancienne page Przelewy24 du même panier est toujours accepté. Si la commande est en attente, la page de confirmation affiche Your payment is being verified. We will send you an e-mail as soon as it is confirmed.

Si le paiement ne peut pas être lancé, le client reste sur le tunnel de commande avec un bref message : Payment error: Przelewy24 could not start the payment. Please try again or choose another payment method. (le motif est écrit dans le journal), Payment gateway is not configured properly. Please contact the administrator. (clés du mode actuel manquantes), un message indiquant que Przelewy24 ne peut pas accepter de paiements dans la devise du panier, ou The order total must be greater than zero. Un panier qui a déjà une commande n'est pas renvoyé à Przelewy24 ; le client est dirigé vers la confirmation de commande.

Le module ne gère ni cartes enregistrées ni paiements en un clic, ni abonnements ni paiements récurrents, ne permet pas de choisir le moyen de paiement P24 (par exemple un champ de code BLIK) sur le tunnel de commande, n'a pas de widgets de paiement en plusieurs fois et n'envoie pas le contenu du panier à Przelewy24.

Commandes et remboursements

Statuts de commande

No order yet : le client a été redirigé vers Przelewy24 et n'a pas payé, ou le paiement n'est pas encore confirmé. Seul le panier existe.

Payment accepted : le paiement a été vérifié. Il est enregistré avec l'identifiant de commande P24 comme identifiant de transaction, et une note indique l'identifiant de commande P24, le montant et le mode. Chaque paiement n'est appliqué qu'une fois.

Przelewy24 payment on hold : le montant ou la devise communiqué par Przelewy24 diffère du panier (par exemple, le panier a été modifié après le lancement du paiement) ; le paiement n'a pas été confirmé et la note l'indique. Ou bien le paiement est arrivé et a été vérifié pour une commande annulée ; la commande n'est pas réouverte silencieusement, la note vous demande de l'expédier ou de rembourser le paiement. Vérifiez le paiement dans le panneau Przelewy24. Si un paiement correct d'une autre tentative arrive plus tard pour une commande en attente après un écart, la commande passe en Payment accepted.

Refunded : le paiement a été intégralement remboursé via le module.

Si un second paiement arrive pour un panier dont la commande est déjà payée ou remboursée (ancien lien de paiement, deux onglets du navigateur), il n'est pas confirmé, donc Przelewy24 ne le crédite pas. Une note sur la commande vous demande de le vérifier dans le panneau Przelewy24 et de le rendre à l'acheteur si nécessaire.

Bloc de paiement Przelewy24

La page de commande affiche un bloc Przelewy24 payment avec l'identifiant de commande P24, la session, l'environnement (un badge Sandbox pour les paiements sandbox), le statut du paiement et sa méthode de vérification (notification ou retour), les montants payés et remboursés, le formulaire de remboursement, l'historique des remboursements et les Payment notes de la commande.

Remboursements

Dans le bloc Przelewy24 payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Przelewy24. Confirmez la question Refund this amount through Przelewy24? This cannot be undone. Les remboursements totaux et partiels sont pris en charge, jusqu'au montant non encore remboursé. Vous devez avoir le droit de modifier les commandes ; l'accès aux pages Modules n'est pas nécessaire. Le remboursement est envoyé dans le mode dans lequel le paiement a été effectué (sandbox ou live), les clés de ce mode doivent donc être renseignées. Les remboursements sont disponibles une fois que Przelewy24 a vérifié le paiement.

Przelewy24 traite les remboursements de manière asynchrone. Le bloc affiche Refund of … requested at Przelewy24. The result will be added as an order note., l'historique des remboursements affiche le statut requested et une note est ajoutée. Le résultat arrive plus tard à l'URL de notification : le statut devient completed avec la note Przelewy24: refund of … completed., ou rejected avec une note indiquant que l'argent n'a pas été rendu à l'acheteur. Un remboursement total passe la commande en Refunded dès sa demande ; un remboursement partiel ne modifie pas le statut. Si un remboursement est rejeté, vérifiez-le dans le panneau Przelewy24 ; le statut de la commande n'est pas rétabli automatiquement.

Si Przelewy24 n'accepte pas la demande de remboursement, le bloc affiche Przelewy24 refund failed: avec le motif, et aucun remboursement n'est enregistré. 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 Przelewy24, et les remboursements effectués directement dans le panneau Przelewy24 ne sont pas ajoutés à la commande.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Przelewy24 Payment est le premier bloc de Modules > Module Manager > VibeFox Przelewy24 Payment > Configure, au-dessus des réglages. Saisissez la clé dans License key puis 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-przelewy24 et le lien Manage licenses and domains in your account, qui ouvre votre compte vibefox.net. Seuls les employés disposant de la permission 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, Przelewy24 n'est pas affiché aux clients sur le tunnel de 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 : le moyen de paiement est donc masqué pour vous aussi. Vous pouvez configurer le module avant d'acheter une clé, mais pas le tester sur le tunnel de commande. 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 vérifiés et confirmés, 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 la licence.

Dépannage

Przelewy24 n'apparaît pas sur le tunnel de commande : vérifiez que la licence est active, que Enable/Disable est activé, que le Merchant ID, la clé API et la clé CRC du mode actuel sont saisis (les clés Sandbox tant que Test Mode est activé, les clés Live sinon ; Merchant ID et POS ID en chiffres uniquement) et que la devise du panier est PLN, EUR, GBP ou CZK. Les avertissements en haut des réglages indiquent le problème. Dans Payment > Preferences, vérifiez que le module est autorisé pour la devise du panier, le pays du client et le groupe du client. Les développeurs peuvent modifier la liste des devises avec le hook actionWcpPrzelewy24SupportedCurrencies (uniquement les devises à deux décimales activées pour votre compte Przelewy24).

Le paiement a abouti, mais aucune commande n'a été créée : la notification de Przelewy24 n'a pas atteint votre boutique et le client n'est pas revenu sur la boutique. Vérifiez que la Notification URL est accessible depuis Internet (aucun pare-feu ni authentification HTTP devant) et que le Merchant ID, le POS ID et la clé CRC du mode du paiement sont corrects. Les notifications rejetées sont écrites dans le journal même avec Debug Log désactivé ; consultez le champ Log sur la page du module.

Comment la boutique répond aux notifications : une notification traitée, répétée ou inconnue reçoit une réponse HTTP 200. Sinon, Przelewy24 la renvoie plus tard : 400 (données manquantes ou mal formées), 401 Invalid signature (clé CRC incorrecte, autre Merchant ID ou POS ID), 401 Invalid signature for this payment (notification signée avec les clés de l'autre mode que celui du paiement), 405 (requête non POST), 500 Verification failed (la vérification auprès de Przelewy24 a échoué ; une note est ajoutée une seule fois à la commande, si elle existe), 500 Order could not be created (par exemple, le module est désactivé ; la notification suivante crée la commande sans nouvelle vérification) et 503 Busy, retry later (le panier était en cours de confirmation par une autre requête au même moment).

Le client voit le message Payment error: Przelewy24 could not start the payment : Przelewy24 a rejeté la transaction, généralement à cause de clés incorrectes du mode actuel (les clés sandbox ne fonctionnent qu'en mode sandbox, les clés live uniquement en mode live). L'erreur de Przelewy24 figure dans le journal.

La commande est en Przelewy24 payment on hold après le paiement : lisez les notes du bloc Przelewy24 payment. Le montant ou la devise différait du panier, ou le paiement est arrivé pour une commande annulée. Vérifiez le paiement dans le panneau Przelewy24, puis traitez la commande ou remboursez le paiement.

Un remboursement échoue : This order has no verified Przelewy24 payment. Cannot process refund. signifie que la commande n'a pas été payée par un paiement Przelewy24 vérifié. The payment was made in the Przelewy24 sandbox, but the Sandbox keys are missing. (ou la même chose pour live) signifie que les clés du mode du paiement ont été supprimées ; saisissez-les à nouveau. Invalid refund amount signifie que le montant est vide, n'est pas un nombre, ou dépasse le montant non encore remboursé.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Przelewy24 Payment 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 du module 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 données de paiement Przelewy24 des commandes (sessions, identifiants de commande P24, remboursements) et le statut de commande Przelewy24 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.

Przelewy24 est une marque de son titulaire respectif. Ce module n'est ni affilié à Przelewy24 ni approuvé par Przelewy24.