README

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é)

composer require cawl/thelia-payment
composer require online-payments/sdk-php:^5.0

Installation manuelle

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

2. Installer le SDK Worldline :

composer require online-payments/sdk-php:^5.0

1. Activer le module via la CLI Thelia :

php Thelia module:activate CawlPayment

1. Vider le cache :

rm -rf var/cache/*

Structure du module

local/modules/CawlPayment/
├── Config/
│   ├── config.xml          # Services et configuration
│   ├── module.xml          # Métadonnées du module
│   ├── routing.xml         # Routes
│   ├── schema.xml          # Schéma BDD Propel
│   └── TheliaMain.sql      # Script SQL d'installation
├── Controller/
│   ├── Admin/              # Contrôleurs backoffice
│   └── Front/              # Contrôleurs frontend
├── EventListeners/         # Écouteurs d'événements
├── I18n/                   # Traductions (fr_FR, en_US, es_ES, it_IT, de_DE)
├── Model/                  # Modèles Propel
├── Service/                # Services (CawlApiService)
├── templates/
│   └── backOffice/         # Templates administration
├── CawlPayment.php         # Classe principale du module
└── README.md               # Cette documentation

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

Champ	Description
Test API Key	Clé API pour l'environnement de test
Test API Secret	Secret API pour l'environnement de test
Test Webhook Key	Clé webhook pour l'environnement de test
Test Webhook Secret	Secret webhook pour valider les notifications

Identifiants de Production

Champ	Description
Production API Key	Clé API pour l'environnement de production
Production API Secret	Secret API pour l'environnement de production
Production Webhook Key	Clé webhook pour l'environnement de production
Production Webhook Secret	Secret webhook pour valider les notifications

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

Catégorie	Méthodes
Cartes bancaires	Visa, Mastercard, CB, American Express, Maestro, JCB, Diners Club
Portefeuilles	PayPal, Apple Pay, Google Pay, WeChat Pay, Alipay
Virements bancaires	iDEAL, Bancontact, Giropay, EPS, Przelewy24, Sofort, SEPA
Paiement fractionné	Klarna (Pay Now, Pay Later, Slice It), Oney 3x/4x
Titres restaurant	Edenred, Sodexo, Up Déjeuner

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

Option	Description
Montant minimum	Montant minimum pour utiliser ce mode de paiement (0 = pas de minimum)
Montant maximum	Montant maximum autorisé (0 = pas de maximum)

4. Configuration Webhook

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

URL du Webhook

https://votre-site.com/cawlpayment/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.

Option	Description
Activer la whitelist	Active/désactive la vérification des IP sources
Liste des IP autorisées	Liste des adresses IP séparées par des virgules

IP Worldline à autoriser :

# Environnement de test (preprod)
91.208.214.0/24
185.8.52.0/22

# Environnement de production
91.208.214.0/24
185.8.52.0/22

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

Code	Nom	ID Produit
visa	Visa	1
mastercard	Mastercard	3
cb	Carte Bancaire	130
amex	American Express	2
maestro	Maestro	117
jcb	JCB	125
diners	Diners Club	132

Portefeuilles numériques

Code	Nom	ID Produit
paypal	PayPal	840
applepay	Apple Pay	302
googlepay	Google Pay	320
wechatpay	WeChat Pay	863
alipay	Alipay	861

Virements bancaires

Code	Nom	ID Produit	Pays
ideal	iDEAL	809	Pays-Bas
bancontact	Bancontact	3012	Belgique
giropay	Giropay	5408	Allemagne
eps	EPS	5700	Autriche
przelewy24	Przelewy24	3124	Pologne
multibanco	Multibanco	5500	Portugal
twint	TWINT	5600	Suisse

Paiement fractionné (BNPL)

Code	Nom	ID Produit
klarna_paynow	Klarna Pay Now	3301
klarna_paylater	Klarna Pay Later	3302
klarna_sliceit	Klarna Slice It	3303
oney3x	Oney 3x	5110
oney4x	Oney 4x	5111

Test du module

Cartes de test

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

Paiement réussi (Frictionless 3DS)

Carte	Numéro	Date	CVV
Visa	4012 0000 3333 0026	Toute date future	123
Mastercard	5399 9999 9999 9999	Toute date future	123

Paiement avec Challenge 3DS

Carte	Numéro	Date	CVV
Visa	4874 9700 0000 0014	Toute date future	123

Paiement refusé

Carte	Numéro	Date	CVV	Raison
Visa	4000 0200 0000 0000	Toute date future	123	Fonds insuffisants

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.

# Montant par défaut : 10,00 EUR
ddev exec php Thelia cawlpayment:test-transaction

# Montant personnalisé (en centimes)
ddev exec php Thelia cawlpayment:test-transaction --amount=4567 --currency=EUR

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 :

ngrok_args: --authtoken=<votre-token>

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

ddev share

1. Copier l'URL publique affichée (ex : https://xxxx.ngrok-free.app)
2. Dans Admin > CawlPayment > Configuration > Test Credentials, renseigner cette URL dans le champ "Test return URL base"
3. 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

ddev exec php vendor/bin/phpunit --configuration local/modules/CawlPayment/phpunit.xml.dist --testsuite "CawlPayment Test Suite"

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

Route	URL	Description
Success	/cawlpayment/success	Retour après paiement réussi
Failure	/cawlpayment/failure	Retour après échec
Cancel	/cawlpayment/cancel	Retour après annulation
Webhook	/cawlpayment/webhook	Réception des notifications

API OpenAPI

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

Endpoint

GET /open_api/payment/module/{moduleId}/options

Réponse

{
  "paymentModuleOptionGroups": [
    {
      "code": "cawl_payment_methods",
      "title": "Choisissez votre moyen de paiement",
      "description": "Sélectionnez le moyen de paiement souhaité",
      "minimumSelectedOptions": 1,
      "maximumSelectedOptions": 1,
      "options": [
        {
          "code": "product_1",
          "title": "Visa",
          "description": "Visa",
          "image": "https://payment.preprod.direct.worldline-solutions.com/...",
          "valid": true
        }
      ]
    }
  ]
}

Initier un paiement via API

POST /cawlpayment/pay/{orderId}/{methodCode}

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 :

rm -rf var/cache/*

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 :

var/log/cawlpayment.log

Format des logs :

[2024-01-15 10:30:00] [CawlPayment] Creating hosted checkout for order #123
[2024-01-15 10:30:01] [CawlPayment] Hosted checkout created: abc123
[2024-01-15 10:32:00] [CawlPayment Webhook] Received webhook notification
[2024-01-15 10:32:00] [CawlPayment Webhook] Order #123 marked as PAID

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 : support@cawl-solutions.com
• 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.