VibeFox Redsys for WooCommerce — Aide

Prérequis

WordPress : 6.2 ou ultérieur.

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

PHP : 8.0 ou ultérieur.

Compte commerçant Redsys : votre banque (l'acquéreur qui vous a fourni le TPV virtuel Redsys) vous remet le code marchand (FUC), le numéro de terminal et l'accès à l'interface d'administration Redsys, où s'affiche la clé secrète SHA-256 de chaque environnement. La clé de l'environnement de test est différente de celle de l'environnement réel. La notification en ligne (HTTP) doit être active pour votre terminal. Demandez à votre banque en cas de doute.

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

Site accessible : Redsys doit pouvoir joindre votre site 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 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_redsys_gateway dans /wp-content/plugins/ par FTP.

2. Cliquez sur Activate.

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

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

5. Saisissez votre code marchand, votre terminal et la clé secrète de chaque environnement (voir Configuration).

6. Activez Enable/Disable. Testez un paiement avec Test Mode activé, puis décochez Test Mode pour accepter les paiements réels.

Configuration

Tous les réglages se trouvent sur une seule page : WooCommerce > Settings > Payments > Redsys. 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 moyen de paiement est alors masqué au moment du paiement) et si la devise de la boutique n'est pas prise en charge. Lorsque 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. Après l'enregistrement, les avertissements suivent immédiatement les nouveaux réglages. Dans la liste des moyens de paiement, Redsys est signalé comme nécessitant une configuration tant que le code marchand, le terminal et la clé du mode actuel ne sont pas valides.

Général

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

Title: le nom du moyen de paiement que voient les clients au moment du paiement. Par défaut : Credit/Debit Card (Redsys).

Description: le texte affiché sous le moyen de paiement au moment du 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 à l'interface d'administration Redsys, où s'affiche la clé secrète SHA-256 de chaque environnement. La section renvoie vers l'interface 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). 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: Enable test mode envoie les paiements et remboursements vers l'environnement de test de Redsys (SIS-T) et les signe avec la clé de test. Par défaut : activé. Décochez-le pour accepter les paiements réels. Lorsqu'il est activé, le paiement affiche TEST MODE: Redsys test environment, no real money is charged. sous le moyen 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.

Page de paiement et commandes

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

Order Status After Payment: le statut de commande défini après un paiement réussi. Le statut n'est défini qu'une seule fois, afin que le client ne reçoive qu'un seul courriel.

Notifications de paiement

Redsys transmet chaque paiement à l'adresse de notification de votre boutique. Elle a la forme https://your-site/wc-api/rdsg_redsys/ et s'affiche dans cette section. L'extension la transmet à Redsys avec chaque paiement : vous n'avez donc rien à copier dans l'interface Redsys. La notification en ligne (HTTP) doit être active pour votre terminal. Demandez à votre banque si les commandes restent en attente de paiement après un paiement réussi. Les notifications sans signature valide sont rejetées. Sans notification, une commande n'est pas marquée comme payée.

Avancé

Debug log: Enable debug logging écrit les détails des paiements, notifications et remboursements dans WooCommerce > Status > Logs, source wcp_redsys_gateway. Les erreurs sont toujours journalisées, même si cette option est désactivée. Les clés, signatures et données de carte ne sont jamais journalisées. Par défaut : désactivé.

Delete Data: Delete the gateway settings when the plugin is deleted. Lorsqu'elle est activée, la suppression de l'extension efface les réglages de la passerelle et les journaux de l'extension. 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 moyen de paiement est masqué pour les autres devises. Sur la page Pay for order, c'est la devise de la commande qui compte.

Paiement

Le client choisit le moyen de paiement (par défaut Credit/Debit Card (Redsys)) et passe commande. La commande passe au statut « En attente de paiement » et le client voit Redirecting to Redsys for payment. Please wait..., puis accède à la page de paiement Redsys de votre banque. Si le navigateur ne poursuit pas automatiquement, le client clique sur Pay via Redsys. 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 de votre boutique (espagnol, anglais, catalan, français, allemand, italien, portugais et d'autres), ou l'anglais pour les autres langues.

Le montant est envoyé dans les plus petites unités monétaires de la devise de la commande, par exemple EUR 43,45 sous la forme 4345, et JPY ou CLP sans décimales. Le paiement est décrit comme Order avec le numéro de commande et le nom de votre site. Le stock n'est diminué qu'une fois le paiement confirmé, et non avant.

Après le paiement, le client revient sur la page de confirmation de commande de votre boutique. La commande n'est marquée comme payée qu'après la confirmation de Redsys par la notification signée. Tant qu'elle n'est pas arrivée, la page affiche Redsys is confirming your payment. If you completed the payment, your order will be updated in a few moments — please do not pay again.

Si le client annule ou si le paiement est refusé, Redsys renvoie le client vers votre boutique. Pour une commande passée au paiement, la commande est annulée de la manière standard de WooCommerce et le panier est conservé. Pour une commande créée depuis l'administration (un lien de paiement), le client revient sur la page Pay for order avec le message The Redsys payment was not completed. You can try again or choose another payment method., et la commande n'est pas annulée. La page de redirection de votre boutique propose également Cancel order & restore cart ou, pour les commandes créées depuis l'administration, Choose another payment method.

Un client peut payer à nouveau une commande impayée depuis la page Pay for order. Chaque 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, reste reconnu.

Si la commande ne peut pas être envoyée à Redsys, le client voit un bref message et peut choisir un autre moyen de paiement : 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.

Le moyen de paiement fonctionne sur le paiement classique, sur le bloc Paiement et sur la page Pay for order. Il est compatible avec WooCommerce High-Performance Order Storage (HPOS).

L'extension prend des paiements uniques, autorisés et capturés immédiatement sur la page Redsys. Elle n'a pas de formulaire de carte sur votre propre site (InSite ou iframe), pas de cartes enregistrées, de paiements en un clic ou de tokenisation, pas d'abonnements ni de paiements récurrents, pas de préautorisation avec capture ultérieure et pas de notifications SOAP.

Commandes et remboursements

Statuts de commande

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

Processing, Completed or On Hold: le paiement a été confirmé. Le statut suit Order Status After Payment. La note de commande affiche le numéro de commande Redsys (Ds_Order), le code d'autorisation et le code de réponse, suivis de [TEST] pour les paiements test. L'ID de transaction de la commande est le numéro de commande Redsys.

On hold after payment: Redsys a signalé un montant ou une devise différent du total de la commande, un paiement test est arrivé alors que la boutique est en production (aucun argent réel n'a été débité), ou le paiement est arrivé après l'annulation de la commande. La note de commande l'explique. Vérifiez le paiement dans l'interface d'administration Redsys, puis expédiez la commande ou remboursez le paiement.

Failed: le paiement a été refusé ou annulé chez Redsys. La note de commande affiche le code de réponse et, pour les codes les plus courants, une brève explication telle que Insufficient funds, Card expired ou Cancelled by the customer. Seule une commande encore en attente de paiement passe au statut Échec. Une commande payée ou clôturée n'est jamais modifiée par une tentative refusée : la tentative est seulement notée.

Cancelled: le client a annulé le paiement, ou la commande a été annulée par vous ou par le délai de réservation des stocks de WooCommerce.

Si un second paiement, différent, arrive pour une commande déjà payée ou remboursée, la commande n'est pas modifiée. Une note vous invite à rembourser le paiement en double dans l'interface 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 définitif.

Remboursements

Ouvrez la commande, cliquez sur Refund, saisissez le montant et cliquez sur le bouton de remboursement via le moyen de paiement Redsys (par défaut Refund via Credit/Debit Card (Redsys)). Les remboursements totaux et partiels sont pris en charge. Le remboursement est envoyé via l'API REST de Redsys vers l'environnement dans lequel le paiement a été effectué (test ou production), 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, WooCommerce affiche l'erreur et aucun remboursement n'est enregistré. Un remboursement réussi est ajouté aux notes de commande avec le numéro de commande Redsys et le motif.

Les remboursements effectués dans l'interface d'administration Redsys ne sont pas enregistrés comme remboursements WooCommerce. Lorsque Redsys envoie une notification à ce sujet, une note est ajoutée à la commande. Si nécessaire, créez un remboursement manuel dans WooCommerce sans utiliser le bouton de remboursement Redsys.

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 > Redsys. 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 sur 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, Redsys n'est pas affiché 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. Les gestionnaires de la boutique connectés 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 l'assistance nécessitent un renouvellement. Le statut est vérifié à nouveau automatiquement en arrière-plan.

Dépannage

Redsys n'apparaît pas au moment du 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 production. Vérifiez que la devise de la boutique (sur la page Pay for order, la devise de la commande) figure dans la liste des devises prises en charge. La page des réglages affiche un avertissement pour chacun de ces problèmes.

Le paiement a abouti, mais la commande reste en Pending payment : 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 Notifications de paiement est joignable depuis Internet sans connexion, sans page de maintenance et sans blocage par un pare-feu. Activez Debug log et consultez WooCommerce > Status > Logs, source wcp_redsys_gateway.

La notification répond Forbidden : la signature ne correspondait pas à la clé secrète de l'environnement dans lequel le paiement a été lancé, ou le code marchand de la notification n'est pas le vôtre. 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 aucune commande de cette boutique n'utilise ce numéro de commande Redsys.

La notification répond Busy : la commande était en cours de traitement par une autre notification au même moment. Redsys renouvelle la notification.

La notification répond Bad request : la requête ne contenait pas de paramètres Redsys, ou ceux-ci étaient incorrects. Elle ne provenait pas de Redsys dans le format attendu.

La commande est On hold after payment : lisez la note de commande. Le montant ou la devise payé différait de la commande, un paiement test est arrivé alors que la boutique est en production, ou le paiement est arrivé après l'annulation de la commande. Expédiez la commande ou remboursez le paiement.

Les paiements test ne confirment pas les commandes en production : un paiement test ne règle jamais une commande lorsque 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 filtre rdsg_currency_codes. N'ajoutez une devise que si votre banque l'a activée pour le terminal.

Après une mise à jour depuis la version 1.0 : la clé que vous utilisiez en mode test se trouve désormais dans Secret Key (SHA-256) — test. Saisissez la clé de production avant de décocher Test Mode. Les commandes créées avec la version 1.0 reçoivent toujours les notifications et les remboursements.

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

La désactivation de 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 sont toujours supprimés. Les réglages de la passerelle et les journaux de l'extension ne sont supprimés que si Delete Data était activé ; sinon, ils restent disponibles pour une réinstallation ultérieure. Les données Redsys enregistrées sur les commandes sont toujours conservées, car elles documentent les paiements et sont nécessaires aux remboursements. Les commandes existantes conservent leurs notes de paiement et leurs ID de transaction.

Redsys est une marque déposée de son propriétaire. Cette extension n'est pas affiliée à Redsys et n'est pas approuvée par Redsys.