Download the PHP package thelia/cawl-payment-module without Composer

CawlPayment - Module de Paiement CAWL Solutions pour Thelia 2.6

Module de paiement intégrant la passerelle CAWL Solutions / Worldline pour Thelia 2.6. Supporte plus de 30 méthodes de paiement incluant les cartes bancaires, portefeuilles numériques, virements et paiement fractionné.

Table des matières

• Fonctionnalités
• Prérequis
• Installation
• Configuration
  • Identifiants API
  • Méthodes de paiement
  • Options
  • Webhook
• Méthodes de paiement supportées
• Test du module
• Intégration Frontend
• API OpenAPI
• Dépannage
• Sécurité
• Changelog
• Support

Fonctionnalités

• 30+ méthodes de paiement : Cartes (Visa, Mastercard, CB, Amex), PayPal, Apple Pay, Google Pay, Klarna, Bancontact, iDEAL, etc.
• Environnement Test/Production : Basculement facile entre les modes
• Hosted Checkout : Page de paiement sécurisée hébergée par Worldline
• Webhooks : Notifications de paiement en temps réel avec validation de signature HMAC-SHA256
• Multi-langue : FR, EN, ES, IT, DE
• Compatible OpenAPI : Intégration native avec le module OpenApi de Thelia
• Logs détaillés : Journalisation configurable pour le débogage
• Dashboard de test : Interface d'administration pour tester l'API

Prérequis

• Thelia : Version 2.6.x
• PHP : 8.2 ou supérieur
• Extensions PHP : curl, json, openssl
• SDK Worldline : online-payments/sdk-php: ^5.0 (installé via Composer)
• Compte CAWL Solutions : Identifiants API (PSPID, API Key, API Secret)

Installation

Via Composer (recommandé)

Installation manuelle

1. Télécharger le module et le placer dans local/modules/CawlPayment/

2. Installer le SDK Worldline :

3. Activer le module via la CLI Thelia :

4. Vider le cache :

Structure du module

Configuration

Accédez à la configuration via : Administration > Modules > CawlPayment > Configurer

1. Identifiants API

Environnement

Sélectionnez l'environnement actif :

• Test : Pour les développements et tests (sandbox Worldline)
• Production : Pour les transactions réelles

PSPID (Merchant ID)

Votre identifiant marchand CAWL Solutions. Cet identifiant est fourni lors de la création de votre compte.

Identifiants de Test

Identifiants de Production

Important : Ne jamais utiliser les identifiants de test en production et vice-versa.

Tester la connexion

Cliquez sur le bouton "Tester la connexion" pour vérifier que vos identifiants sont corrects. Un message de succès ou d'erreur s'affichera.

2. Méthodes de paiement

Sélectionnez les méthodes de paiement à proposer à vos clients. Les méthodes sont chargées dynamiquement depuis l'API CAWL en fonction de votre contrat.

Catégories disponibles

3. Options

Journalisation

• Activer les logs : Active l'enregistrement des requêtes/réponses API dans var/log/cawlpayment.log

Attention : Désactivez les logs en production pour des raisons de performance et de confidentialité.

Limites de montant

4. Configuration Webhook

Les webhooks permettent de recevoir les notifications de paiement en temps réel (confirmation, échec, remboursement, etc.).

URL du Webhook

Configuration dans le back-office CAWL

1. Connectez-vous au Portail Marchand CAWL (test) ou Production
2. Allez dans Configuration > Webhooks
3. Ajoutez l'URL du webhook de votre site
4. Copiez la Webhook Key et le Webhook Secret générés
5. Collez-les dans la configuration du module Thelia

Événements webhook supportés

• payment.created - Paiement initié
• payment.pending_capture - En attente de capture
• payment.captured - Paiement capturé
• payment.cancelled - Paiement annulé
• payment.rejected - Paiement rejeté
• payment.refunded - Remboursement effectué

Sécurité Webhook - Whitelist IP

Pour renforcer la sécurité des webhooks, vous pouvez activer une whitelist d'adresses IP autorisées. Seules les requêtes provenant des IP listées seront acceptées.

IP Worldline à autoriser :

Note : La whitelist IP est une couche de sécurité supplémentaire. La validation de signature HMAC-SHA256 reste la méthode principale de vérification.

Méthodes de paiement supportées

Cartes bancaires

Portefeuilles numériques

Virements bancaires

Paiement fractionné (BNPL)

Test du module

Cartes de test

Utilisez ces numéros de carte dans l'environnement de test :

Paiement réussi (Frictionless 3DS)

Paiement avec Challenge 3DS

Paiement refusé

Test de connexion API

Depuis l'interface de configuration du module (Administration > Modules > CawlPayment > Configurer), le bouton "Test API Connection" (en haut à droite) permet de vérifier que les identifiants sont corrects et que l'API Worldline est accessible.

Créer une transaction de test (commande console)

La commande cawlpayment:test-transaction permet de créer une transaction sandbox sans passer par le checkout Thelia. Elle vérifie automatiquement la configuration avant de lancer le paiement.

La commande effectue 7 vérifications avant de créer le checkout :

1. Environnement Thelia ≠ production
2. Module configuré sur "test"
3. PSPID configuré
4. api_key_test configurée
5. api_secret_test configuré
6. Au moins une méthode de paiement activée
7. Connexion API live (appel sandbox)

En cas d'échec, un message indique précisément quelle configuration est manquante.

Tester le callback de retour (URL de test)

Après le paiement, Worldline redirige vers l'URL de retour du module. En développement local (DDEV), cette URL n'est pas accessible depuis les serveurs Worldline car *.ddev.site résout sur 127.0.0.1.

Solution : exposer DDEV via ngrok

1. Installer ngrok : sudo snap install ngrok
2. Créer un compte gratuit sur ngrok.com et récupérer l'authtoken

3. Configurer DDEV dans .ddev/config.yaml :

4. Démarrer le tunnel dans un terminal dédié (laisser tourner) :

5. Copier l'URL publique affichée (ex : https://xxxx.ngrok-free.app)
6. Dans Admin > CawlPayment > Configuration > Test Credentials, renseigner cette URL dans le champ "Test return URL base"
7. Relancer cawlpayment:test-transaction

Worldline redirigera vers l'URL ngrok après le paiement. Le résultat (statut, paymentId, isPaid) est enregistré dans var/log/log-thelia.txt avec le préfixe [CawlPayment][test-return].

Note : le plan gratuit ngrok affiche une page d'avertissement à la première visite — cliquer sur "Visit Site" pour continuer.

Créer une transaction de test (interface admin)

Depuis Admin > CawlPayment > Configuration > Test Credentials, un panneau "Create a test transaction" permet de lancer un checkout sandbox sans passer par le terminal :

1. Saisir le montant en euros et la devise (défaut : 10,00 EUR)
2. Cliquer "Create test transaction" — le module vérifie la configuration puis appelle l'API
3. Un lien "Open checkout" apparaît avec le hostedCheckoutId — cliquer pour accéder à la page de paiement Worldline
4. Après le paiement, utiliser le panneau "Module logs" (juste en dessous) et cliquer "Refresh" pour voir le statut retourné par Worldline ([CawlPayment][test-return])

Cette interface équivaut à ddev exec php Thelia cawlpayment:test-transaction --amount=<n> --currency=EUR sans quitter le navigateur.

Lancer les tests unitaires

Intégration Frontend

Flux de paiement standard

1. Le client sélectionne CawlPayment comme mode de paiement
2. Le client choisit sa méthode de paiement (carte, PayPal, etc.)
3. Redirection vers la page Hosted Checkout de Worldline
4. Le client effectue le paiement
5. Redirection vers la page de confirmation Thelia
6. Le webhook confirme le statut final du paiement

URLs de callback

API OpenAPI

Le module s'intègre avec le module OpenApi de Thelia pour exposer les options de paiement.

Endpoint

Réponse

Initier un paiement via API

Dépannage

Erreurs courantes

"No payment mode available"

Cause : Aucune méthode de paiement n'est activée ou les identifiants API sont incorrects.

Solution :

1. Vérifiez que le PSPID est configuré
2. Testez la connexion API
3. Activez au moins une méthode de paiement

"Invalid webhook signature"

Cause : Le secret webhook ne correspond pas ou n'est pas configuré.

Solution :

1. Vérifiez que le Webhook Secret est correctement copié depuis le portail CAWL
2. Assurez-vous d'utiliser le bon secret (test vs production)

"Controller not callable"

Cause : Le cache Symfony n'est pas à jour.

Solution :

Commande payée mais statut "Not paid"

Cause : Le webhook n'a pas été reçu ou traité.

Solution :

1. Vérifiez l'URL du webhook dans le portail CAWL
2. Vérifiez les logs dans var/log/cawlpayment.log
3. Assurez-vous que votre serveur accepte les requêtes POST externes

Logs

Les logs sont enregistrés dans :

Format des logs :

Sécurité

Bonnes pratiques implémentées

• Chiffrement AES-256-GCM des credentials API en base de données (SecureConfigService)
• Validation HMAC-SHA256 des webhooks
• Pas d'exposition des erreurs internes aux utilisateurs
• Journalisation sécurisée (pas de credentials dans les logs)
• Injection de dépendances pour les services
• Protection CSRF sur les formulaires admin
• Vérification des permissions admin

Recommandations

1. Désactivez les logs en production
2. Utilisez HTTPS obligatoirement
3. Configurez le Webhook Secret en production
4. Limitez les accès au back-office
5. Mettez à jour régulièrement le module

Checklist mise en production

Avant de basculer en mode production, vérifier les points suivants :

• [ ] Basculer l'environnement sur production dans Admin > CawlPayment > Environment
• [ ] Renseigner les credentials de production (PSPID, API Key, API Secret, Webhook Key, Webhook Secret)
• [ ] Vérifier le comportement de capture sur le compte marchand CAWL production :
  • Auto-capture activée → le paiement passe directement en statusCode=9 (CAPTURED) après autorisation. Le webhook notifie quasi immédiatement et la commande est confirmée automatiquement.
  • Capture manuelle → le paiement reste en statusCode=5 (PENDING_CAPTURE) jusqu'à capture explicite depuis le portail marchand. La commande ne sera pas confirmée automatiquement — à adapter selon le process métier.
  • ⚠️ Ce point est critique : un compte en capture manuelle sans process de capture explicite laissera les commandes en attente indéfiniment.
• [ ] Configurer l'URL webhook dans le portail CAWL production (https://votre-site.fr/cawlpayment/webhook)
• [ ] Désactiver les logs (Admin > CawlPayment > Options > Enable logging)
• [ ] Tester un paiement réel à faible montant et vérifier le statut dans le portail marchand

Changelog

Voir CHANGELOG.md pour l'historique complet des versions.

Version 1.1.0 (2026-06-24)

• Interface admin de test : création de transaction sandbox sans terminal
• Viewer de logs [CawlPayment] avec rafraîchissement en temps réel
• Commande console cawlpayment:test-transaction avec vérifications pré-flight
• Support ngrok : champ test_base_url + guide d'installation dans l'admin
• Fix : showResultPage(false) pour déclencher la redirection Worldline
• Fix : webhook_key sorti du chiffrement AES (identifiant, pas un secret)
• Tests unitaires : CawlApiService, SecureConfigService, webhook, transactions

Version 1.0.1 (2026-06-24)

• Correction compatibilité Thelia 2.6 (services, hooks, routing)
• Migration SDK online-payments/sdk-php v5 (DefaultConnection)
• Réécriture back-office : Bootstrap 3 natif, suppression CSS custom
• Chiffrement AES-256-GCM des credentials API en base de données

Version 1.0.0 (2024-12)

• Version initiale
• Support de 30+ méthodes de paiement
• Intégration Hosted Checkout Worldline
• Support webhooks avec validation signature
• Multi-langue (FR, EN, ES, IT, DE)
• Intégration OpenAPI

Bugs connus

Aucun bug connu pour le moment.

Corrigé (voir CHANGELOG [Unreleased]) — les méthodes de paiement sont désormais filtrées en mode test : createTestHostedCheckout() applique PaymentProductFilters à partir des méthodes activées dans Admin > CawlPayment > Payment Methods, comme en production.

Support

Documentation officielle

• Documentation CAWL Solutions
• SDK PHP Worldline v5
• Portail Marchand Test
• Portail Marchand Production

Contact

Pour toute question ou problème :

• Email : [email protected]
• Documentation Thelia : https://doc.thelia.net/

Licence

Ce module est distribué sous licence propriétaire CAWL Solutions.

© 2026 CAWL Solutions - Tous droits réservés.