Leanpay

Contexte

Leanpay permet les achats "paiement échelonné" pour les commerçants e-commerce. Pour les boutiques WooCommerce et OpenCart, l'intégration doit s'adapter au cycle de vie de processus de paiement/commande de chaque plateforme, communiquer clairement les prix échelonnés sur la vitrine et rester opérationnellement sûre face aux résultats asynchrones (flux de redirection + callbacks serveur).

Problème

Les paiements échelonnés ajoutent de la complexité au-delà d'une simple redirection :

• Les commerçants ont besoin de plans d'échelonnement à jour (par marché et produit/groupe financier).
• Le processus de paiement doit rediriger vers le flux Leanpay et retourner le client en toute sécurité.
• La finalisation de la commande doit être pilotée par un callback serveur vérifié pour empêcher les états "succès" falsifiés.
• Les administrateurs ont besoin de visibilité opérationnelle (statut, logs/métadonnées) et d'actions (par ex. confirmation de livraison).

Objectifs du Projet

• Fournir Leanpay comme méthode de paiement de premier ordre dans WooCommerce et OpenCart.
• Afficher les prix échelonnés et une interface calculatrice sur les pages catalogue/produit/processus de paiement.
• Maintenir les plans d'échelonnement synchronisés automatiquement et à la demande.
• Finaliser les commandes via des callbacks de statut vérifiés et stocker les métadonnées Leanpay sur les commandes/transactions.
• Prendre en charge plusieurs marchés/environnements Leanpay et ensembles de fonctionnalités de plateforme communes.

Contraintes et Défis

• Garder le chemin de callback autoritaire (jamais "statut par URL de redirection").
• Prévenir les décalages d'arrondi/devises et appliquer les limites min/max spécifiques au marché.
• Maintenir une configuration admin conviviale pour les commerçants (paramètres WooCommerce ; paramètres multi-boutiques OpenCart).
• Garantir que les widgets de vitrine réagissent aux totaux du panier et aux variations de produit sans casser l'UX du processus de paiement.

Aperçu de la Solution

Nous avons construit des modules Leanpay pour deux plateformes avec un objectif commun : processus de paiement échelonné sécurisé + UX de tarification échelonnée cohérente.

• WooCommerce : passerelle + widgets d'échelonnement + synchronisation de plan planifiée + actions de boîte méta de commande admin.
• OpenCart : extension de paiement + widgets d'échelonnement basés sur événements + stockage local de transaction/plan + configuration admin + amélioration OCMOD pour le statut de liste de commandes.

Architecture et Approche Technique

Module WooCommerce

Configuration de la passerelle (wp-admin)

• Clé API + secret, environnement (production/sandbox), point de terminaison marché (`si`, `hr`, `ro`, `hu`).
• URL de callback affichée en lecture seule "API Vendor URL" à copier dans la configuration vendeur Leanpay.
• Totaux de commande min/max pour la disponibilité et liste d'autorisation IP optionnelle en sandbox.
• Titre/description de paiement + statuts de commande pour succès/échec et pages de redirection personnalisées optionnelles.

Synchronisation et stockage des plans d'échelonnement

• Crée une table de base de données WP personnalisée (`wp_leanpay_cene_tmp_2022`) lors de l'activation.
• Récupère `vendor/installment-plans` par marché et stocke les groupes de plans et les prix localement.
• Prend en charge les mises à jour planifiées quotidiennes et une action manuelle "Mettre à jour les prix des produits" dans les paramètres.

Widgets d'affichage de vitrine

• Catalogue : étiquette "à partir de X / mois" injectée dans les boucles de produits.
• Produit : tooltip calculatrice avec curseur jQuery UI ; prix de variation mis à jour via AJAX.
• Processus de paiement : affichage d'échelonnement et enrichissement de titre de passerelle dynamique optionnel.
• Shortcodes : `[leanpay_catalog]`, `[leanpay_product_page]`.

Initiation de paiement (token → processus de paiement)

• `process_payment()` redirige vers un script de confirmation interne.
• Requête de jeton vers `https://{env}.leanpay.{market}/vendor/token` et soumission de formulaire vers `https://{env}.leanpay.{market}/vendor/checkout`.
• Le payload inclut l'ID de transaction vendeur, le montant, les données de facturation, la langue et les articles du panier.

Vérification du callback de statut

• Le point de terminaison de callback analyse le JSON et résout la commande depuis `vendorTransactionId`.
• Valide `md5Signature` en utilisant `API_secret` et met à jour le statut de commande de manière déterministe.
• Stocke les métadonnées de commande de diagnostic (par ex. `leanpay_vendor_transaction_id`, `leanpay_order_status`).

Opérations de commande admin

• La boîte méta de commande (IDs d'écran HPOS-safe) affiche le statut Leanpay et active les actions opérationnelles.
• Action AJAX pour la confirmation de livraison (`/vendor/transaction/delivery`).
• Action AJAX pour le statut du document de vérification (`/api/verification-document/get`) stockée dans les méta de commande.

Compatibilité WooCommerce Blocks + HPOS

• Déclare la compatibilité avec `custom_order_tables` (HPOS) et `cart_checkout_blocks`.
• Enregistre un script d'intégration de méthode de paiement Blocks (`assets/js/checkout.js`).

Module OpenCart

Flux de passerelle de paiement

• Valide la devise de base et les totaux min/max (valeurs par défaut spécifiques au marché ; par ex. RO diffère).
• Crée un UUID `vendorTransactionId` et le stocke dans `mojakoda_leanpay_transactions`.
• Demande un jeton via Leanpay et redirige vers `vendor/checkout?token=...`.

Callback vérifié + mappage d'état de commande

• Point de terminaison de statut : `index.php?route=extension/payment/leanpay/status`.
• Valide le schéma JSON et vérifie la signature MD5 en utilisant le "mot secret" configuré.
• Mappe `SUCCESS` au statut "payé" configuré (avec note d'audit) et stocke le statut dans la table de transactions.

Synchronisation des plans d'échelonnement + stockage local

• Stocke les groupes et le JSON `loanAmounts` dans `mojakoda_leanpay_installments` par pays.
• L'admin sélectionne quel groupe d'échelonnement utiliser pour le rendu de vitrine.

Widgets d'échelonnement de vitrine (Événements)

• Injecte l'UI d'échelonnement sur les pages de produits (tooltip + curseur), processus de paiement et listes de catégories.
• Charge jQuery UI + `leanpay.css` pour l'UI calculatrice.

UX admin + opérations

• Paramètres multi-boutiques (optionnel "paramètres globaux"), restriction de zone géographique, ordre de tri et journalisation de débogage.
• OCMOD ajoute une colonne "Statut Leanpay" à la liste de commandes admin, provenant de la table de transactions.

Stack Technologique

• WordPress + WooCommerce (passerelle + intégration Blocks)
• OpenCart (extension de paiement + Événements + OCMOD)
• PHP (modules de plateforme, vérification de callback, persistance locale)
• JavaScript/CSS (widgets, curseur jQuery UI, UI des paramètres admin)
• APIs vendeur Leanpay (jeton, processus de paiement, plans d'échelonnement, callbacks de statut)

Processus d'Implémentation

1. Définir le modèle d'état de commande et rendre le callback vérifié autoritaire.
2. Implémenter l'UX des paramètres de passerelle et la gestion environnement/marché par plateforme.
3. Implémenter la récupération de plan d'échelonnement + stockage local + sélection admin.
4. Ajouter les widgets de vitrine (catalogue/produit/processus de paiement) et mises à jour sensibles aux variations/panier.
5. Implémenter la validation de signature de callback et la finalisation de commande déterministe.
6. Ajouter les outils d'opérations admin (actions de boîte méta WooCommerce ; statut de liste de commandes OpenCart via OCMOD).

Résultats et Impact

• Les commerçants peuvent offrir des paiements échelonnés Leanpay sur WooCommerce et OpenCart avec finalisation de commande prévisible.
• Les clients voient les prix échelonnés tôt et obtiennent une UX calculatrice cohérente tout au long du processus de paiement.
• Les opérations obtiennent visibilité et actions dans l'admin (métadonnées de statut de commande, flux de livraison/vérification, logs).
• Les données de plan d'échelonnement restent à jour via des mises à jour en arrière-plan avec remplacements manuels.

Réflexion

Pour les paiements échelonnés, la stabilité vient du traitement du callback serveur signé comme seule source de vérité. Le flux de redirection/retour est un chemin UX, pas un signal d'autorisation. Cela empêche les états "payé" falsifiés et réduit la charge de support causée par des résultats ambigus.

Résumé

Leanpay a été intégré dans WooCommerce et OpenCart comme solution de paiement échelonné sécurisée avec stockage de plan local, widgets de tarification de vitrine et callbacks de statut vérifiés. Le package OpenCart inclut en plus une amélioration OCMOD qui affiche le statut Leanpay dans la liste de commandes admin.