VibeFox Przelewy24 for WooCommerce — Aide

Prérequis

WordPress : 5.8 ou ultérieur.

WooCommerce : 7.0 ou ultérieur, installé et activé. L'extension refuse de s'activer sans lui.

PHP : 8.0 ou ultérieur.

Devise : la commande doit être en PLN, EUR, GBP ou CZK. Dans les autres devises, le moyen de paiement est masqué au moment du paiement. La commande est débitée dans sa propre devise ; l'extension 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 trouverez 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. Il n'y a rien d'autre à configurer dans le panneau Przelewy24 : l'extension envoie son URL de notification avec chaque paiement. Votre site doit être accessible depuis Internet, car Przelewy24 y envoie les notifications de paiement.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne pour un 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_przelewy24_payment dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

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

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

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

6. Saisissez les clés de production, décochez Test Mode et enregistrez pour accepter de vrais paiements.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Przelewy24. Au-dessus des champs, la page affiche des avertissements lorsqu'un élément 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 de production). Si Przelewy24 n'accepte pas la devise de la boutique, l'avertissement indique cette devise et les devises prises en charge. Après l'enregistrement, les avertissements suivent immédiatement le nouveau mode et les nouvelles clés. Les espaces et sauts de ligne copiés avec les clés depuis le panneau Przelewy24 sont supprimés à l'enregistrement.

Paiement

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 affiché aux clients au moment du paiement. Par défaut : Przelewy24.

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

Identifiants API

Cette section indique 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 : Enable sandbox (test) mode. Lorsqu'il est activé, les nouveaux paiements sont envoyés au sandbox de Przelewy24 (sandbox.przelewy24.pl) avec les clés sandbox, et aucun argent réel n'est débité. Décochez-le pour accepter de vrais paiements sur secure.przelewy24.pl avec les clés de production. Par défaut : activé.

Clés de production

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, avec le POS ID.

Live CRC key : sert à signer les requêtes envoyées à Przelewy24 et à vérifier la signature des notifications 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 de production 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é au moment du paiement. 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 de mode ; conservez donc les clés de l'ancien mode tant que ses paiements sont encore ouverts ou peuvent être remboursés.

Notifications de paiement

Cette section affiche l'URL de notification de votre boutique. Elle ressemble à https://your-site/wc-api/wc_p24_payment/. L'extension envoie cette URL à Przelewy24 avec chaque paiement : rien n'est à configurer dans le panneau Przelewy24. La même URL reçoit les résultats des remboursements. Cette URL doit être accessible depuis Internet : aucun pare-feu, mode maintenance ni authentification HTTP ne doit la bloquer. Sans notifications, un paiement est tout de même confirmé lorsque le client revient sur la page « commande reçue » (voir Paiement) ; si le client ne revient pas, la commande reste en « En attente de paiement ».

Avancé

Debug Log : Enable logging écrit les événements techniques (numéros de commande, identifiants de transaction P24, erreurs) dans WooCommerce > Status > Logs, source wcp_przelewy24_payment. Les erreurs et avertissements sont toujours consignés. Les clés, le contenu des requêtes et les données personnelles ne sont jamais consignés. Par défaut : désactivé.

Delete data on uninstall : Delete the plugin settings and logs when the plugin is deleted. Les commandes et leurs données de paiement ne sont jamais supprimées. Désactiver l'extension conserve tout. Par défaut : désactivé.

Paiement

Le client choisit le moyen de paiement (par défaut Przelewy24, avec le logo P24 sur le bloc Paiement) et passe la commande. En mode sandbox, le bloc Paiement affiche Sandbox mode — no real money is charged. L'extension enregistre une transaction Przelewy24 pour le total de la commande dans la devise de la commande, avec l'e-mail, le nom et le pays de facturation du client, et ajoute une note de commande avec l'identifiant de session et le mode (sandbox ou production). 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 site si Przelewy24 la prend en charge, sinon en anglais.

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

Après le paiement, le client revient sur la page « commande reçue ». Si la notification n'est pas encore arrivée, l'extension demande à Przelewy24 le statut de la transaction par une requête serveur à serveur authentifiée (au plus une fois toutes les 10 secondes par commande) et applique les mêmes contrôles. La page de retour seule ne marque jamais une commande comme payée. Tant que le paiement n'est pas confirmé, la page 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 Pay again qui ouvre la page Pay for order. Si la commande est en attente, la page affiche Your payment is being verified. We will send you an e-mail as soon as it is confirmed. Un paiement effectué plus tard sur une ancienne page Przelewy24 de la même commande reste accepté.

Si le paiement ne peut pas démarrer, le client voit un bref message : Payment error: Przelewy24 could not start the payment. Please try again or choose another payment method. (la raison est consignée 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 de la commande, ou The order total must be greater than zero. Une commande déjà payée ou en attente n'est pas renvoyée à Przelewy24 (This order does not need a payment any more.).

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

L'extension ne gère ni cartes enregistrées ni paiements en un clic, ni abonnements ni paiements récurrents, ni le choix du moyen de paiement P24 (par exemple un champ de code BLIK) sur votre page de paiement, ni widgets de paiement en plusieurs fois, et n'envoie pas le contenu du panier à Przelewy24.

Commandes et remboursements

Statuts de commande

Pending payment : le client a été redirigé vers Przelewy24 et n'a pas encore payé, ou le paiement n'est pas encore confirmé.

Processing or Completed : le paiement a été vérifié. WooCommerce passe la commande en « En cours », ou en « Terminée » pour les commandes ne contenant que des produits virtuels téléchargeables. La note de commande indique l'identifiant de commande P24, le montant et le mode. L'identifiant de transaction de la commande est l'identifiant de commande P24. Chaque paiement n'est appliqué qu'une seule fois.

On hold : le montant ou la devise communiqués par Przelewy24 diffèrent de la commande (par exemple, le total 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 rouverte silencieusement, la note vous demande de l'expédier ou de rembourser le paiement. Vérifiez le paiement dans le panneau Przelewy24.

Si un second paiement arrive pour une commande 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 restituer à l'acheteur si nécessaire.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur Refund via Przelewy24. Les remboursements totaux et partiels sont pris en charge. Le remboursement est envoyé dans le mode dans lequel le paiement a été effectué (sandbox ou production), donc les clés de ce mode doivent être renseignées. Przelewy24 traite les remboursements de façon asynchrone : la note de commande indique d'abord que le remboursement a été demandé, puis le résultat arrive à l'URL de notification et s'ajoute en note : Przelewy24: refund of … completed., ou une note indiquant que le remboursement a été refusé et que l'argent n'a pas été restitué. Si un remboursement est refusé, vérifiez-le dans le panneau Przelewy24 ; le remboursement WooCommerce déjà enregistré sur la commande n'est pas supprimé automatiquement.

Si Przelewy24 n'accepte pas la demande de remboursement, WooCommerce affiche Przelewy24 refund failed: avec la raison, et aucun remboursement n'est enregistré. Les remboursements effectués directement dans le panneau Przelewy24 ne sont pas ajoutés à la commande.

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 > Przelewy24. Collez la clé dans License key et cliquez sur Activate. Le bloc affiche le statut, par exemple la date jusqu'à laquelle la licence est active, et votre domaine. Utilisez Check now pour vérifier à nouveau le statut, 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 pour un seul domaine. Retirer la clé d'un site ne libère pas son emplacement de domaine. Libérez-le dans votre compte vibefox.net.

Sans clé active, Przelewy24 n'est pas affiché aux clients au moment du paiement. Si un paiement est lancé malgré tout, le client voit This payment method is not available. Please choose another one. Les gestionnaires connectés de la boutique voient toujours le moyen 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 Plugins et sur les pages WooCommerce. Les commandes existantes ne sont pas affectées : les paiements déjà lancés sont toujours confirmés, et les remboursements fonctionnent.

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 en arrière-plan.

Dépannage

Przelewy24 n'apparaît pas au moment du paiement : 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 de production sinon ; Merchant ID et POS ID uniquement en chiffres) et que la devise de la commande est PLN, EUR, GBP ou CZK. Les avertissements en haut des réglages indiquent le problème. Les développeurs peuvent modifier la liste des devises avec le filtre wc_p24_supported_currencies (uniquement les devises à deux décimales activées pour votre compte Przelewy24).

Le paiement a abouti, mais la commande reste en Pending payment : la notification de Przelewy24 n'a pas atteint votre boutique et le client n'est pas revenu sur la page « commande reçue ». Vérifiez que l'URL affichée sous Payment notifications est accessible depuis Internet (aucun mode maintenance, pare-feu ni authentification HTTP devant /wc-api/wc_p24_payment/) et que le Merchant ID, le POS ID et la clé CRC du mode du paiement sont corrects. Les notifications rejetées sont consignées dans WooCommerce > Status > Logs, source wcp_przelewy24_payment, même si Debug Log est désactivé.

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, ou notification signée avec les clés de l'autre mode que celui du paiement), 405 (requête autre qu'un POST), 500 Verification failed (la vérification auprès de Przelewy24 a échoué ; une note est ajoutée à la commande une seule fois) et 503 Busy, retry later (la commande était en cours de mise à jour par une autre requête au même moment).

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

La commande est On hold après le paiement : lisez la note de commande. Le montant ou la devise différait de la commande, 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 la production) signifie que les clés du mode du paiement ont été supprimées ; saisissez-les à nouveau.

Le bloc de licence affiche une erreur : suivez le message affiché dans le 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 avec le dernier statut connu.

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 le statut de licence de cette extension, ainsi que les marqueurs temporaires de la page de retour, sont toujours supprimés. Les réglages de l'extension et ses journaux (fichiers journaux, y compris ceux rotés, et entrées de journal en base de données de la source wcp_przelewy24_payment) ne sont supprimés que si Delete data on uninstall était activé. Sinon, ils sont conservés pour une future réinstallation. Les commandes existantes conservent leurs notes de paiement, leurs identifiants de transaction et leurs données de paiement Przelewy24.

Przelewy24 est une marque de son titulaire respectif. Cette extension n'est ni affiliée à Przelewy24 ni approuvée par Przelewy24.