Vue d'ensemble de l'architecture
L'intégration LodinPay s'intercale entre votre plateforme e-commerce et la passerelle Lodin. Cette page documente l'architecture au niveau dont vous avez besoin en tant qu'intégrateur.
Acteurs du système
| Acteur | Rôle |
|---|---|
| Navigateur du client | Initie le paiement et reçoit les redirections |
| Plateforme e-commerce | PrestaShop, Shopify, Shopware, WooCommerce, Odoo, ou sur mesure |
| Module Lodin | Le plugin que nous livrons — embarqué dans votre plateforme |
| Passerelle Lodin | Hébergée par Lodin — dialogue avec les banques, héberge la page de paiement |
| Banque du client | Réalise la SCA et exécute le SCT Inst |
Le module Lodin est le seul composant que nous livrons dans votre infrastructure. Tout le reste est soit votre code, soit externe à nous deux.
Frontières de responsabilité
| Préoccupation | Responsable |
|---|---|
| Afficher l'option de paiement au checkout | Module Lodin (via le hook de votre plateforme) |
| Création et persistance de la commande | Votre plateforme (ses API natives) |
| Génération du lien de paiement | Passerelle Lodin (le module appelle l'API) |
| Authentification du client (SCA) | Banque du client |
| Mouvement des fonds (SCT Inst) | Banque vers banque, orchestré par Lodin |
| Notification du statut de paiement | Passerelle Lodin → votre module (webhook) |
| Mise à jour de l'état de la commande | Module Lodin → votre plateforme |
| Préparation, livraison, reçu | Votre plateforme — hors périmètre |
Cette frontière est volontaire : LodinPay ne touche jamais à votre logistique, à votre logique d'expédition ni à vos données client au-delà du strict nécessaire pour le paiement. Cela limite la surface réglementaire et rend l'intégration testable.
Composants du module
Le module livré se décompose en quatre composants internes, chacun avec une responsabilité unique et claire :
- Initiation du paiement — crée la commande en attente, construit le jeton de retour, prépare l'appel API.
- Générateur de lien de paiement — signe et envoie la requête API, retourne l'URL de la page hébergée.
- Récepteur de webhooks — vérifie les signatures entrantes, pilote la machine à états des commandes, gère l'idempotence et la réconciliation des montants.
- Gestionnaire de retour — vérifie le jeton de retour, s'aligne sur l'état courant de la commande, affiche la page de confirmation ou de nouvelle tentative.
La séquence détaillée se trouve dans Flux de paiement ; les transitions d'état dans Machine à états des commandes.
Configuration
Deux valeurs vous sont remises par Lodin lors de l'onboarding marchand et sont stockées par le module :
| Clé | Rôle |
|---|---|
LODIN_CLIENT_ID | Identifie votre compte marchand auprès de la passerelle |
LODIN_CLIENT_SECRET | Clé HMAC partagée, utilisée pour signer les requêtes et vérifier les webhooks |
Les deux sont cloisonnés par environnement : les valeurs sandbox ne peuvent pas atteindre la production, et inversement.
Prérequis de déploiement
- HTTPS sur chaque page touchant au flux de paiement (obligatoire pour les redirections porteuses de SCA).
- HTTPS sortant vers
api.lodinpay.com(production) ouapi-preprod.lodinpay.com(sandbox). - POST entrant depuis Lodin vers votre URL de webhook. Pensez à autoriser l'en-tête
X-Webhook-Signatureau niveau de votre WAF / CDN. - Horloge serveur précise (NTP). Le
X-Timestampsigné est présent sur chaque appel API ; une dérive supérieure à 5 minutes provoque le rejet de toutes les requêtes. - Pas de liste blanche d'adresses IP sortantes qui exclurait nos plages — demandez nos plages actuelles au support si votre politique de sécurité l'exige.
Voir aussi
- Flux de paiement — séquence de bout en bout avec canaux de retour parallèles.
- Machine à états des commandes — les quatre états logiques et leurs transitions.
- Modèle de sécurité — flux cryptographiques et menaces couvertes.