VibeFox Redsys for PrestaShop — Aide

Prérequis

PrestaShop : 8.0 à 9.x.

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

Compte commerçant Redsys : votre banque (l'acquéreur qui vous a fourni le TPV virtuel Redsys) vous donne le code marchand (FUC), le numéro de terminal et l'accès au panneau d'administration Redsys, où la clé secrète SHA-256 de chaque environnement est affichée. La clé de l'environnement de test est différente de la clé réelle. La notification en ligne (HTTP) doit être active pour votre terminal. Interrogez votre banque si vous n'êtes pas sûr.

Devise de la boutique : l'une des devises prises en charge par le module (voir Configuration), et votre terminal Redsys doit être activé par la banque pour cette devise. La plupart des terminaux n'acceptent que l'EUR.

Boutique accessible : Redsys doit pouvoir atteindre votre boutique depuis Internet, sans connexion ni blocage par un pare-feu, pour transmettre les notifications de paiement.

Clé de licence VibeFox : achetée sur vibefox.net. Une clé fonctionne sur un 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 Redsys Gateway 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 votre code marchand, votre terminal et la clé secrète de chaque environnement (voir Configuration).

5. Activez Enable/Disable et cliquez sur Save. Testez un paiement avec Test Mode activé, puis désactivez Test Mode pour accepter les paiements réels.

À l'installation, le module crée le statut de commande Redsys payment on hold. PrestaShop propose le nouveau module de paiement pour les pays actifs à ce moment-là, et pour toutes les devises et tous les groupes de clients. Vous pouvez modifier cela dans Payment > Preferences ; les pays que vous activerez plus tard doivent y être cochés pour le module.

Configuration

Tous les réglages se trouvent sur la page du module : Modules > Module Manager > VibeFox Redsys Gateway > Configure. Chaque section a son propre bouton Save, qui enregistre la page entière. Au-dessus des champs, la page vous avertit si le code marchand est absent ou ne contient pas uniquement des chiffres, si une clé secrète n'est pas une clé SHA-256 Redsys valide, si la clé du mode actuel est vide (le mode de paiement est alors masqué à l'étape de paiement) et si la devise de la boutique n'est pas prise en charge. Tant que le mode test est activé, elle affiche Test mode is active: payments go to the Redsys test environment (SIS-T), no real money is charged. Si Title est vide, la page affiche Enter a title for the payment method. et rien n'est enregistré.

Redsys

Enable/Disable : Enable Redsys Gateway active ou désactive le mode de paiement. Par défaut : désactivé.

Title : le nom du mode de paiement que voit le client à l'étape de paiement. C'est aussi le nom du mode de paiement enregistré dans la commande. Par défaut : Credit/Debit Card (Redsys). Obligatoire.

Description : le texte affiché sous le mode de paiement à l'étape de paiement. Par défaut : Pay securely with your credit or debit card via Redsys.

Compte Redsys

Votre banque vous fournit le code marchand, le terminal et l'accès au panneau d'administration Redsys, où la clé secrète SHA-256 de chaque environnement est affichée. La section contient un lien vers le panneau d'administration Redsys.

Merchant Code (FUC) : votre code marchand Redsys, jusqu'à 9 chiffres. Tout caractère qui n'est pas un chiffre est supprimé à l'enregistrement.

Terminal Number : le numéro de terminal attribué par votre banque, jusqu'à 3 chiffres. Par défaut : 1. Un champ vide est enregistré comme 1.

Secret Key (SHA-256) — live : la clé SHA-256 en Base64 de l'environnement réel (production), généralement de 32 caractères. Elle est utilisée lorsque le mode test est désactivé.

Mode test (SIS-T)

L'environnement de test de Redsys a sa propre clé secrète. La section affiche les données publiques de test de Redsys : code marchand 999008881, terminal 1, clé sq7HjrUOBfKmC576ILgskD5srU870gJ7, carte 4548 8100 0000 0003, expiration 12/49, CVV 123. Aucun argent réel n'est débité en mode test.

Test Mode : les paiements et remboursements sont envoyés à l'environnement de test de Redsys (SIS-T) et signés avec la clé de test. Par défaut : activé. Désactivez-le pour accepter de vrais paiements. Tant qu'il est activé, l'étape de paiement affiche TEST MODE: Redsys test environment, no real money is charged. sous le mode de paiement.

Secret Key (SHA-256) — test : la clé SHA-256 en Base64 de l'environnement de test. Utilisez votre propre clé de test ou la clé publique de test indiquée ci-dessus.

Les clés 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.

Page de paiement et commandes

Commerce Name : le nom de la boutique affiché sur la page de paiement Redsys, de 25 caractères maximum. Par défaut : le nom de votre boutique, tronqué à 25 caractères.

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

Les écarts de montant ou de devise, les paiements test alors que la boutique est en mode réel et les paiements issus de tentatives annulées vont toujours en Redsys payment on hold.

Notifications de paiement

Notification URL : Redsys signale chaque paiement à cette adresse de votre boutique. Elle est affichée dans cette section et ressemble à https://your-shop/module/wcp_redsys_gateway/notify avec les URL conviviales. Le module la transmet à Redsys avec chaque paiement : vous n'avez rien à copier dans le panneau Redsys. La notification en ligne (HTTP) doit être active pour votre terminal. Interrogez votre banque si aucune commande n'est créée après un paiement réussi. Les notifications sans signature valide sont rejetées. Sans la notification, aucune commande n'est créée.

Avancé

Debug log : écrit les détails des paiements, des notifications et des remboursements dans logs/rdsg_debug.log.php, dans le dossier du module. Le fichier ne peut pas être ouvert depuis le web. Les erreurs sont toujours consignées, même si cette option est désactivée. Les clés, les signatures et les données de carte ne sont jamais consignées. 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 : lorsqu'elle est activée, la désinstallation du module supprime les réglages de la passerelle et le journal. Les enregistrements de paiement Redsys des commandes (nécessaires aux remboursements) et le statut de commande Redsys payment on hold sont toujours conservés. Par défaut : désactivé.

Devises prises en charge

EUR, USD, GBP, JPY, CHF, CAD, AUD, NZD, NOK, SEK, DKK, PLN, CZK, HUF, BGN, RON, ILS, INR, MYR, SGD, THB, SAR, ZAR, RUB, BRL, MXN, ARS, CLP, COP, PEN, CNY, TWD. Le mode de paiement est masqué pour les paniers dans d'autres devises.

Paiement

À l'étape de paiement, le client choisit le mode de paiement (par défaut Credit/Debit Card (Redsys)) et confirme la commande. Le client voit Redirecting to Redsys for payment. Please wait... et passe sur la page de paiement Redsys de votre banque. Si le navigateur ne poursuit pas tout seul, le client clique sur Pay via Redsys, ou sur Choose another payment method pour revenir en arrière. Aucune commande n'existe encore à ce stade.

Sur la page Redsys, le client paie par carte avec 3-D Secure, ou par Bizum ou un autre moyen activé par votre banque pour le terminal. La page utilise la langue du panier (espagnol, anglais, catalan, français, allemand, italien, portugais et d'autres), ou l'anglais pour les autres langues. Le montant correspond au total du panier dans la plus petite unité de la devise du panier, par exemple EUR 43,45 devient 4345, et JPY ou CLP sans décimales. Le paiement est décrit comme Cart avec le numéro de panier et le nom de votre boutique.

Après le paiement, le client revient dans votre boutique. La commande n'est marquée comme payée qu'après la confirmation de Redsys par la notification signée : c'est la notification qui crée la commande, et le client voit la page standard de confirmation de commande avec Your payment with Redsys has been received. Si la commande est passée en Redsys payment on hold, la page affiche Your payment with Redsys has been received and is being reviewed by the store. Si la notification n'est pas encore arrivée, une page Payment confirmation affiche Redsys is confirming your payment. If you completed the payment, your order will be created in a few moments — please do not pay again. avec les boutons Check again et Back to checkout.

Si le client annule ou si le paiement est refusé, Redsys renvoie le client à l'étape de paiement avec le message The Redsys payment was not completed. You can try again or choose another payment method. Le panier est conservé et le client peut payer à nouveau. Chaque nouvelle tentative reçoit un nouveau numéro de commande Redsys, et un paiement effectué depuis l'une d'elles, par exemple depuis un second onglet du navigateur, est tout de même reconnu.

Si le paiement ne peut pas être envoyé à Redsys, le client reste à l'étape de paiement avec un bref message : Redsys payments are not configured correctly. Please choose another payment method or contact us., un message indiquant que la devise n'est pas acceptée, ou The order total must be greater than zero.

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

Le module accepte des paiements uniques, autorisés et capturés immédiatement sur la page Redsys. Il ne propose ni formulaire de carte sur votre propre site (InSite ou iframe), ni cartes enregistrées, paiements en un clic ou tokenisation, ni abonnements ou paiements récurrents, ni préautorisation avec capture ultérieure, ni liens de paiement pour les commandes créées dans le back office.

Commandes et remboursements

Statuts de commande

No order yet : le client a été envoyé vers Redsys et n'a pas payé, le paiement a été refusé ou annulé, ou la notification de Redsys n'est pas encore arrivée. Seul le panier existe.

Payment accepted, Delivered or Redsys payment on hold : le paiement a été confirmé. Le statut suit Order Status After Payment. Le paiement est enregistré avec le numéro de commande Redsys (Ds_Order) comme identifiant de transaction, et une note indique le numéro de commande Redsys, le code d'autorisation et le code de réponse, avec la mention [TEST] pour les paiements test.

Redsys payment on hold after payment : Redsys a signalé un montant ou une devise différent du total du panier (par exemple, le panier a été modifié dans un autre onglet après le début du paiement), un paiement test est arrivé alors que la boutique est en mode réel (aucun argent réel n'a été débité et aucun paiement n'est enregistré), ou le client a payé après avoir annulé ce paiement sur la page Redsys. La note explique la situation. Vérifiez le paiement dans le panneau d'administration Redsys, puis traitez la commande ou remboursez le paiement.

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

Un paiement refusé ne modifie jamais une commande existante. Pour les codes de réponse les plus fréquents, le journal et les notes donnent une raison brève, comme Insufficient funds, Card expired ou Cancelled by the customer. Si un second paiement différent arrive pour un panier qui a déjà une commande, la commande n'est pas modifiée. Une note vous demande de rembourser le paiement en double dans le panneau d'administration Redsys. Si Redsys indique qu'un paiement est encore en cours, une note est ajoutée et la commande attend le résultat final.

Bloc de paiement Redsys

La page de commande affiche un bloc Redsys payment avec le numéro de commande Redsys (Ds_Order), le code et la réponse d'autorisation, l'environnement (réel ou test), le montant payé et remboursé, un badge Test mode pour les paiements test, une indication de contrôle pour les commandes en attente, l'historique des remboursements, les Redsys notes de la commande et tous les numéros de commande Redsys émis pour le panier.

Remboursements

Dans le bloc Redsys payment, saisissez le montant (le montant non encore remboursé est prérempli), éventuellement un motif, puis cliquez sur Refund via Redsys. Confirmez la question Refund this amount through Redsys? This cannot be undone. Les remboursements totaux et partiels sont pris en charge. Vous devez avoir le droit de modifier les commandes ; l'accès aux pages des modules n'est pas nécessaire. Les remboursements s'effectuent dans le montant et la devise que Redsys a débités : après un écart de montant ou de devise, vous pouvez donc rembourser jusqu'au montant réellement payé par le client, et non jusqu'au total de la commande. Le remboursement est envoyé via l'API REST de Redsys à l'environnement dans lequel le paiement a été effectué (test ou réel), signé avec la clé de cet environnement, et la signature de la réponse est vérifiée. Si Redsys n'accepte pas le remboursement, le bloc affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté à l'historique des remboursements et aux notes, avec le numéro de commande Redsys et le motif. Un remboursement total passe la commande en Refunded. Un remboursement partiel ne modifie pas le statut.

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 Redsys.

Les remboursements effectués dans le panneau d'administration Redsys ne sont pas enregistrés comme remboursements du module. Lorsque Redsys envoie une notification à ce sujet, une note est ajoutée à la commande. Le statut de commande ne change pas automatiquement.

Clé de licence

Le module fonctionne avec une clé de licence VibeFox obtenue sur vibefox.net. Le bloc de licence License — VibeFox Redsys Gateway est le premier bloc de la page Modules > Module Manager > VibeFox Redsys 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-redsys 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 : celui 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, Redsys 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 boutique PrestaShop ne sait pas que vous êtes connecté au back-office, si bien que le moyen de paiement vous est aussi masqué : vous pouvez configurer le module avant d'acheter une clé, mais pas le tester au moment du 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à lancés sont toujours 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

Redsys n'apparaît pas à l'étape de paiement : vérifiez que la licence est active, que Enable/Disable est activé, que le code marchand et le terminal sont renseignés et que le mode actuel dispose d'une clé valide : Secret Key (SHA-256) — test en mode test, Secret Key (SHA-256) — live en mode réel. Vérifiez que la devise du panier figure dans la liste des devises prises en charge. La page des réglages affiche un avertissement pour chacun de ces problèmes. 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 abouti, mais aucune commande n'a été créée : la notification Redsys n'a pas atteint votre boutique. Demandez à votre banque de vérifier que la notification en ligne (HTTP) est active pour votre terminal. Vérifiez que l'adresse affichée dans Notification URL est accessible depuis Internet, sans connexion ni blocage par un pare-feu. Activez Debug log et consultez le champ Log sur la page du module.

La notification répond Forbidden : la signature ne correspond pas à la clé secrète de l'environnement dans lequel le paiement a été lancé, ou le code marchand de la notification ne vous appartient pas. Vérifiez que les clés secrètes et le code marchand des réglages sont ceux de votre terminal.

La notification répond Order not found : la notification était correctement signée, mais aucun panier de cette boutique n'utilise ce numéro de commande Redsys.

La notification répond Busy : le panier était en cours de traitement par une autre notification au même moment, ou la commande n'a pas pu être créée (par exemple, le module est désactivé). Redsys relance la notification. Le journal indique la raison.

La notification répond Bad request : la requête ne contenait aucun paramètre Redsys ou contenait des paramètres corrompus. Elle ne provenait pas de Redsys au format attendu.

La commande est Redsys payment on hold après le paiement : lisez les notes du bloc Redsys payment (voir Statuts de commande), puis traitez la commande ou remboursez le paiement.

Les paiements test ne confirment pas les commandes en mode réel : un paiement test ne paie jamais une commande tant que Test Mode est désactivé. La commande est alors mise en attente avec une note. Utilisez le mode test avec la clé de test pour les paiements test.

Le remboursement échoue : lisez l'erreur. Redsys refund: the merchant code or the TEST secret key is not configured. (ou LIVE) signifie que la clé de l'environnement du paiement est absente. Les codes d'erreur Redsys sont expliqués dans le message, par exemple SIS0057 (le montant dépasse ce qui reste du paiement), SIS0056 (le paiement d'origine est introuvable : autre environnement ou terminal), SIS0042 (erreur de signature, vérifiez la clé de cet environnement), SIS0026 (code marchand ou terminal inconnu) et SIS0027 (devise non configurée pour le terminal). Si Redsys est injoignable, le remboursement n'est pas effectué. Réessayez plus tard.

Votre terminal accepte une devise absente de la liste : les développeurs peuvent modifier la liste des devises avec le hook actionRdsgCurrencyCodes. N'ajoutez une devise que si votre banque l'a activée pour le terminal.

Désinstallation

Allez dans Modules > Module Manager, ouvrez le menu à côté de VibeFox Redsys Gateway et choisissez Uninstall. La clé de licence et le statut de licence de ce module sont toujours supprimés. Si Delete Data 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 réinstallation ultérieure. Les enregistrements de paiement et de remboursement Redsys ainsi que le statut de commande Redsys 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.

Redsys est une marque déposée de son titulaire respectif. Ce module n'est ni affilié à Redsys ni approuvé par Redsys.