Wallee Payment Plugin pour Shopware 6

Documentation

1Sommaire

Le plugin de paiement Wallee intègre un traitement moderne des paiements dans Shopware 6, offrant des fonctionnalités telles que les paiements basés sur iFrame, les remboursements, les captures et la conformité PCI. Il permet une intégration transparente avec le portail Wallee pour la gestion des transactions et des méthodes de paiement.

Important : Veuillez noter que seules les mises à jour majeures (par exemple 6.x.0.0) et mineures (par exemple 6.0.x.0) seront testées pour la compatibilité dans les 2 semaines suivant la publication.

2Pré-Requis

Shopware Version: 6.5.x or 6.6.x (voir tableau de compatibilité).

PHP: Version minimale requise pour votre installation Shopware (e.g., 7.4+).

Compte Wallee: Obtenir Space ID, User ID, et clé API du Portail Wallee (voir le Guide de démarrage du Portail).

3Compatibilité

Shopware Version

Plugin Version

PHP Version

Support Until

6.6.x

6.x.x

PHP 8.2 and 8.3

En cours

6.5.x - Deprecated

5.x.x

PHP 8.2 and 8.3

October 2024

4Installation

4.1Via Marketplace

  1. Connectez-vous au backend de votre boutique Shopware.

  2. Naviguez vers Paramètres → Système → Plugins.

  3. Cliquez sur la flèche du menu et sélectionnez le lien d’installation du plugin à installer

    plugin installation

  4. Activez le plugin wallee Payment à partir du gestionnaire de plugins

4.2Via Composer (Recommendé)

  1. Naviguez jusqu’au répertoire racine de votre Shopware.

  2. Exécutez:

    composer require wallee/shopware-6
php bin/console plugin:refresh
php bin/console plugin:install --activate --clearCache WalleePayment

4.3Via Composer (Recommended)

Téléchargez la dernière version. . Extrayez le ZIP dans custom/plugins/ . Exécutez

+

php bin/console plugin:refresh
php bin/console plugin:install --activate --clearCache WalleePayment

5Guide de démarrage pour le Portail

Allez sur wallee et créez un Compte si vous n’en avez pas déjà un

Tip
 Veuillez sélectionner le plan d’abonnement approprié - il doit prendre en charge les transactions de e-commerce.

5.1Créez la clé API:

  1. Une fois que votre compte est activé, naviguez vers Compte → Utilisateurs de l’application

    application users

  2. Cliquez sur Créer un utilisateur d’application

    user

  3. Spécifiez un nom pour cette Clé API - par exemple Test Shop - et cliquez sur Créer un utilisateur user

    api key

  4. Votre utilisateur d’application est ainsi créé. Veuillez copier l’User ID et la Clé d’authentification, car vous en aurez besoin pour reliez votre magasin au portail.

    token

  5. Enfin, vous devrez accorder certaines autorisations à cet utilisateur d’application afin qu’il puisse communiquer avec votre espace. Pour ce faire, sous Rôle, naviguez jusqu’à Gérer.

    roles

  6. Cliquez sur le sign + à côté de Space Roles

    assign role

  7. Veuillez ajouter le rôle Space Admin et cliquez sur and click on Assign Role.

    Tip
    		 Veuillez noter que le chargement des rôles peut durer quelques secondes.
    loading roles

  8. Enfin, cliquez sur Enregistrer les Roles; vous devrez entrer votre mot de passe pour confirmer.

    save role

5.2Configurer les modes de paiement

Vous pouvez maintenant configurer les méthodes de paiement que vous souhaitez utiliser ; à des fins de test, nous utiliserons le Bogus Processor. Veuillez noter que si vous souhaitez effectuer une transaction de production, vous pouvez utiliser notre offre Payfac ou vous connecter directement à un PSP spécifique (Worldline ; ACI ; …​).

  1. Naviguez vers Space → Paramètres et cliquez sur Processors

    payment settings

  2. Cliquez sur Configurez le processeur

  3. Sélectionnez Bogus Processor et cliquez sur Continue

    bogus processor

  4. Définissez le nom que vous souhaitez donner à votre processeur - e.g. Test Processor - et cliquez sur Créer

    name processor

  5. Sélectionnez tous les connecteurs qui s’appliquent et cliquez sur Enregistrer

    Tip
    		 Veuillez noter que les connecteurs semblent faire double emploi, mais c’est parce que l’un concerne le paiement par terminal physique et l’autre le paiement par ecommerce.
    connectors

Les méthodes de paiement sont désormais disponibles dans le portail.

6Guide de démarrage pour Shopware

  1. Identifiants API

    1. Naviguez vers Shopware Admin → Paramètres → Extensions → Wallee Payment et cliquez sur Sauvegarder.

    2. Entrez votre Space ID, User ID, et clé API

      1. Pour le Space id; vous pouvez naviguer vers le Space et il sera fourni - par exemple, l’identifiant du Space id = 76231

        plugin configuration

  2. Méthodes de Paiment

    Les méthodes de paiement disponibles à la caisse sont gérées par le Portail Wallee. Si vous souhaitez désactiver une méthode de paiement, vous devez la désactiver à partir du portail.

    Note
    		 Veuillez noter qu’en raison de la synchronisation entre le portail et la boutique, vous pouvez effectuer la même opération à partir de la boutique, sous Paramètres → Méthodes de paiement.

    1. a.Allez dans Space → Paramètres → Paiements → Méthodes de Paiement

      payment methods

    2. Sélectionnez le mode de paiement que vous souhaitez désactiver. Cliquez sur le curseur pour le désactiver → il devrait devenir inactif.

      cc enable
      cc disable
      Tip
      		 Si vous souhaitez désactiver uniquement un Connecteur d’un mode de paiement (par exemple, Mastercard pour une carte de crédit), veuillez consulter la section Connecteur.

  3. Options

    1. Space View Id: Ce champ vous permet d’appliquer un style personnalisé au formulaire et à la page de paiement. Le style est défini dans les paramètres de votre espace dans le portail.

      Note
      		 Veuillez noter que si vous n’utilisez pas Space View Id, cette option doit rester vide.

    2. Intégration: Le paramètre Options d’intégration détermine comment le formulaire de paiement est affiché pendant la procédure de paiement. Les options suivantes sont disponibles :

      1. IFrame: Incorpore le formulaire de paiement directement dans la page de paiement de Shopware pour une expérience transparente.

      2. Lightbox: Ouvre une fenêtre contextuelle sécurisée pour que les clients puissent effectuer leur paiement sans quitter la page de paiement.

      3. Payment Page: Redirige les clients vers une page de paiement dédiée, hébergée par le fournisseur de paiement.

    3. Consistence des articles: Shopware calcule les taxes au niveau de l’article, ce qui peut entraîner des différences mineures (généralement de quelques centimes) entre le total des taxes de la commande et le prix affiché. Cet écart est dû à des différences d’arrondi lors du calcul de chaque article. Si le paramètre « Renforcer la cohérence » est activé, le portail rejettera automatiquement les commandes présentant de tels écarts. Pour éviter les problèmes liés au traitement des paiements, nous vous recommandons de désactiver ce paramètre, à moins qu’une validation stricte du total des taxes ne soit nécessaire.

    4. Envoyer un email de confirmation de commande: Activez cette option pour envoyer des emails de confirmation de commande directement depuis Shopware au lieu du portail.

      order confirmation email

7Différents Etats pour une Transaction

Le processus de paiement de wallee est complètement standardisé pour chaque méthode de paiement que vous pouvez traiter. Cela vous permet d’ajouter simplement une méthode de paiement ou un processeur sans modifier la configuration de votre Shopware. Une vue d’ensemble des états et des processus de paiement de wallee peut être trouvée dans la documentation sur les paiments..

Dans la section suivante, nous vous donnons un aperçu de la façon dont les états de wallee sont mappés dans le graphique des états de Shopware pour les commandes et les états de paiement.

7.1Cartographie des différents états d’une commande de Shopware

Actuellement, nous ne modifions pas l’état de la commande. Nous ne modifions que l’état du paiement et l’état de la livraison.

7.1.1Remarque générales concernant les status des commandes

Nous vous recommandons de ne modifier l’état de la commande que lorsque l’état du paiement est définitif (Payée, Annulée ou Echouée) .

7.2Cartographie des différents états du paiement de Shopware

Vous trouverez ci-dessous un diagramme qui montre l’association des différents états de Shopware pour l’état de paiement pour wallee, ainsi que des informations supplémentaires sur les transitions entre les états.

shopware 6 stage graph order

  1. Si la transaction est Autorisée dans wallee, le statut du paiement de la commande dans le Shopware est marqué comme étant En Cours.

  2. Si la transaction échoue avant ou pendant le processus d’autorisation, le statut du paiement de la commande du Shopware est marqué comme Échouée.

  3. Si la transaction échoue après l’autorisation, le statut du paiement de la commande du Shopware est marqué comme Annulée.

  4. Si la facture de la transaction dans wallee est marquée comme Payée ou Non Applicable, le statut du paiement de la commande dans le Shopware est marqué comme Payée.

7.2.1Remarques générales concernant les différents status pour les paiements

Nous vous recommandons de ne pas modifier manuellement l’état du paiement. Si vous le faites, il peut être modifié à nouveau par le plugin.

7.3Carthographie des différents états de livraison chez Shopware

Vous trouverez ci-dessous un diagramme qui montre les différents états pour la livraison chez Shopware avec des informations supplémentaires pour les transitions d’états.

shopware 6 stage graph delivery

  1. Si la transaction est confirmée dans wallee, le statut de livraison de la commande dans le Shopware est indiqué comme étant En Attente.

  2. Si la transaction dans wallee est marquée comme Délivrée, le statut de livraison de la commande Shopware est marqué comme Ouvert.

  3. Si la transaction est en statut Déclinée, Échouée ou Annulée, le statut de livraison de la commande du Shopware est marqué comme Annulée.

8Gestion des Transactions

Vous pouvez capturer, annuler et rembourser des transactions directement depuis le backend de Shopware. Veuillez noter que si vous remboursez, annulez ou capturez des transactions dans wallee, les événements seront synchronisés dans Shopware. Cependant, il y a quelques limitations (voir ci-dessous).

8.1Complete (capture) an order

Vous avez la possibilité pour vos transactions de n’autoriser le paiement qu’une fois la commande passée. Dans la configuration du connecteur, vous avez la possibilité, si la méthode de paiement le permet, de définir si le paiement doit être effectué immédiatement ou différé.

Pour capturer une transaction, ouvrez la commande et cliquez sur le bouton Terminer.

Note
 Lorsque le paiement est en attente dans wallee, la commande reste en attente.
capture transaction

Finalisation du paiement de manière différée

Les détaillants souhaitent souvent autoriser les transactions et lancer le processus d’exécution une fois que tous les articles peuvent être expédiés. Cela est également possible avec wallee.

Cependant, certains processus doivent être suivis. Si vous avez configuré la finalisation du paiement pour qu’il soit différé, vous devez capturer la transaction avant d’initier l’expédition, car il peut toujours arriver qu’une finalisation échoue. Si vous voulez être sûr de ne pas expédier d’articles pour lesquels vous n’avez pas été payé, vous devez reporter l’expédition jusqu’à ce que l’état Confirmé soit atteint. Au départ, la transaction sera dans l’état Autorisé dans wallee et En cours dans Shopware. Si vous souhaitez lancer le processus d’exécution, assurez-vous de lancer le processus d’achèvement comme décrit ci-dessus. Une fois le processus terminé avec succès, la commande passera à l’état Confirmée dans wallee et à l’état Payée dans Shopware. Vous pouvez maintenant lancer le processus de livraison .

8.2Annuler une transaction

Pour annuler une transaction, ouvrez la commande et cliquez sur le bouton Annuler l’autorisation.

Note
 Vous ne pouvez annuler que les transactions qui ne sont pas encore complétée..
void transaction

8.3Remboursement d’une transaction

Vous avez la possibilité de rembourser des transactions déjà effectuées. Pour ce faire, ouvrez l’ordre saisi. En cliquant sur les 3 points (…​) sur un article, vous pouvez rembourser l’article partiellement (s’il a une quantité supérieure à 1), ou vous pouvez rembourser l’article en entier. Si la méthode de paiement ne prend pas en charge les remboursements, vous n’aurez pas la possibilité d’effectuer des remboursements en ligne.

refund transaction

Vous pouvez effectuer autant de remboursements individuels que vous le souhaitez jusqu’à ce que vous ayez atteint le montant total de la commande initiale. Le statut de la commande passe alors automatiquement à completée.

Note
 Il peut s’écouler un certain temps avant que vous ne voyiez le remboursement dans Shopware. Les remboursements ne seront visibles que lorsqu’ils auront été traités avec succès.

8.4Commandes en attente

La livraison ne doit pas être effectuée tant que l’état de la livraison est en attente. Cela se produit lorsque la transaction dans wallee n’a pas atteint l’état Confirmé.

Il y a essentiellement deux raisons pour lesquelles cela peut se produire :

  • La transaction n’est pas terminée. Dans ce cas, vous devez compléter la transaction comme indiqué ci-dessus..

  • Nous ne sommes pas en mesure de déterminer si vous devez honorer la commande. La décision de livraison est prise automatiquement. Si cela ne se produit pas dans le délai défini, wallee génère une tâche manuelle que vous devez observer et suivre les instructions.

Vous trouverez plus d’informations sur les tâches manuelles dans notre Documentation sur les Tâches Manuelles..

8.5Limites de la synchronisation entre wallee et Shopware

Veuillez noter que les captures, annulations et remboursements effectués dans wallee sont synchronisés. Cependant, il y a quelques limitations. Dans wallee, vous pouvez modifier le prix unitaire et la quantité en une seule fois. Cela n’est pas possible dans le backend du Shopware. Nous vous recommandons donc d’effectuer les remboursements toujours dans le backend de Shopware et non dans wallee. Si un remboursement ne peut pas être synchronisé, il sera envoyé au processeur, mais il se peut que vous ne le voyiez pas dans votre backend Shopware.

Vous pouvez trouver plus d’informations sur les remboursements dans wallee dans notre Documentation sur les Remboursements..

8.6Tokenisation

Si la méthode de paiement prend en charge la tokenisation, vous pouvez stocker les détails de paiement de votre client pour des achats futurs. Afin d’utiliser cette fonctionnalité, assurez-vous que le Mode de paiement en un clic dans la configuration de votre méthode de paiement est réglé sur autoriser ou forcer le stockage.

Note
 La tokenisation n’est pas disponible pour les paiements par les invités.

8.7Caractéristiques Pricinpales

  • Intégration iFrame: Intégrez des formulaires de paiement directement dans votre checkout.

  • Remboursements & Captures: Déclenchez des remboursements complets/partiels et des captures à partir de Shopware ou du portail Wallee.

  • Support Multi-Magasins: Gérez les configurations sur plusieurs magasins.

  • Mises à jour automatiques: Les méthodes de paiement se synchronisent dynamiquement via l’API Wallee.

8.8Troubleshooting

  • Logs: Vérifiez les logs des payments avec:

    tail -f var/log/whitelabelname_payment*.log

  • Problèmes courants:

    • Assurez-vous que la commande composer update whitelabelname/shopware-6 est exécutée après les mises à jour.

    • Vérifier que les identifiants de l’API correspondent à votre compte Wallee.

8.9FAQs

Q: Comment s’assurer que la connexion entre le portail et la boutique fonctionne? A: Vous devez vérifier que les webhooks ont été correctement créés. Pour ce faire, naviguez vers votre espace dans le portail, allez dans Paramètres → Général → Webhook Listeners.

webhooks
webhook listeners

Q: Ce plugin prend-il en charge les paiements en un clic ? A: Oui, via la tokenisation dans le portail Wallee.

Q: Comment gérer la conformité PCI ? A: Le plugin utilise l’intégration iFrame, réduisant les exigences PCI à SAQ-A.

Q: Le plugin prend-il en charge Apple Pay ? A: Oui, le plugin prend en charge les portefeuilles comme Apple Pay.

9Changelog

Pour les mises à jour spécifiques à une version, voir les GitHub Releases.

10Contribuer

Signaler les problèmes via GitHub Issues.

Suivez le Shopware Plugin Base Guide pour le développement.

11Support

Si vous avez besoin d’aide, n’hésitez pas à contacter notre support.