Intégration de l'assurance en paiement mensuel

Vue d'ensemble

L'intégration des paiements mensuels Estaly permet à vos clients de souscrire à des assurances produits avec un modèle de facturation récurrent, offrant ainsi une option financièrement flexible pour protéger leurs achats. Cette documentation décrit le processus d'intégration complet avec le module Estaly et votre PSP.

Fonctionnement général

Le système de paiements mensuels Estaly fonctionne en trois phases principales :

1. Configuration initiale : Installation et paramétrage des modules, synchronisation du catalogue.
2. Souscription client : Première transaction combinant le produit et la mensualité initiale.
3. Gestion du cycle de vie des paiements : Prélèvements récurrents, gestion des échecs de paiement.

Cas d'utilisation principal

Un client achète un smartphone à 300€ et choisit l'assurance casse & vol à 5,99€/mois. Lors du checkout, il paie 305,99€ (produit + première mensualité). Les mois suivants, Estaly gère automatiquement les prélèvements mensuels de 5,99€ sans intervention du marchand.

Prérequis techniques

• Magento 1.9+ (ou version compatible)
• Module Estaly installé et configuré
• Un compte actif auprès d'un PSP compatible (Adyen, Stripe, etc.)
• Support des paiements récurrents activé sur votre compte PSP

1. Configuration initiale

Configuration du PSP (exemple avec Adyen)

Vous devrez configurer votre compte PSP pour permettre les paiements récurrents. Voici les étapes pour Adyen :

Actions requises

1. Dans le dashboard Adyen, activez :

   • Les paiements par carte et SEPA
   • Le mode de capture automatique des paiements
   • Les paiements récurrents (Paramètre Recurring Processing Model : Subscription)
   • Configuration de l'endpoint webhook pour recevoir les notifications Adyen

2. Vérifiez la configuration des webhooks :

   https://votre-boutique.com/adyen/process/webhook

⚠️

Important : La configuration des webhooks est essentielle pour le bon fonctionnement des paiements récurrents. Assurez-vous qu'ils sont correctement configurés et que votre serveur peut les recevoir.

Configuration du module Estaly

Une fois le module PSP configuré, vous devez activer et configurer le support des paiements mensuels dans le module Estaly :

1. Accédez à Admin > Estaly > Configuration > Paiements
2. Activez l'option Paiements mensuels
3. Sélectionnez le PSP à utiliser parmi ceux disponibles
4. Configurez les paramètres de relance en cas d'échec de paiement

// Exemple de configuration JSON exportable
{
  "monthly_payments": {
    "enabled": true,
    "psp": "adyen",
    "retry_days": 3,
    "max_retries": 3,
    "suspend_after_failed_attempts": true
  }
}

2. Flux de souscription et premier paiement

Flux de souscription et paiement initial

Le processus de souscription à une assurance mensuelle comprend plusieurs étapes impliquant différents acteurs du système :

Étape 1 : Sélection et commande

• Le client ajoute un produit à son panier sur votre boutique Magento
• Le client sélectionne l'option d'assurance mensuelle proposée par le module Estaly
• Le client procède au checkout et valide la commande complète

Étape 2 : Traitement du paiement

• Magento transmet au PSP (Adyen) une requête de paiement incluant :
  • Le montant total (produit + première mensualité)
  • L'indicateur de paiement récurrent (recurringProcessingModel: Subscription)
• Le PSP traite le paiement et renvoie à Magento :
  • La confirmation de paiement
  • Un token de moyen de paiement (paymentMethodToken) pour les prélèvements futurs
• Magento transmet cette confirmation au module Estaly

Étape 3 : Enregistrement de la souscription

• Le module Estaly envoie à l'API Estaly les informations essentielles :
  • Le token de paiement
  • Les détails du contrat d'assurance
  • Les références de la commande
• L'API Estaly confirme l'enregistrement de la souscription
• Un email de confirmation est automatiquement envoyé au client

Implémentation technique

1. Front-end : Présentation de l'offre mensuelle

Le module Estaly injecte automatiquement les options d'assurance sur les pages produit et panier. Pour les paiements mensuels, l'affichage utilise un format spécifique :

<!-- Exemple de balisage généré par le module -->
<div class="estaly-insurance-option estaly-monthly" data-product-id="12345" data-plan-type="monthly">
    <span class="estaly-price">5,99€<span class="estaly-price-suffix">/mois</span></span>
    <div class="estaly-description">Protection casse & vol</div>
    <button class="estaly-add-insurance-btn" data-estaly-sku="INS-MONTHLY-12345">Ajouter</button>
</div>

Pour personnaliser l'affichage, connectez-vous à l'interface d'administration Estaly où toutes les options de personnalisation visuelle sont disponibles. Aucune modification de template Magento n'est nécessaire.

2. Back-end : Traitement de la commande

Lorsqu'une commande avec assurance mensuelle est passée, le module Estaly modifie la requête de paiement pour inclure les paramètres de récurrence :

// Extrait du code généré par le module Estaly
public function prepareRecurringPaymentRequest($observer)
{
    $paymentRequest = $observer->getPaymentRequest();
    $quote = $observer->getQuote();
    
    // Vérification de la présence d'une assurance mensuelle
    if ($this->hasMonthlyInsurance($quote)) {
        // Configuration pour paiement récurrent
        $paymentRequest->setRecurringProcessingModel('Subscription');
        $paymentRequest->setStorePaymentMethod(true);
        
        // Paramètres spécifiques au PSP (exemple Adyen)
        if ($this->isPSPAdyen()) {
            $paymentRequest->setAdditionalData([
                'recurringProcessingModel' => 'Subscription'
            ]);
        }
    }
    
    return $paymentRequest;
}

3. Gestion des paiements récurrents

Une fois la souscription initiale effectuée, Estaly gère automatiquement les paiements récurrents. Votre système n'a pas besoin d'intervenir dans ce processus, sauf en cas d'échec de paiement ou d'annulation.

Workflow des prélèvements mensuels

1. À chaque échéance, l'API Estaly initie un appel vers le PSP pour prélever la mensualité
2. Le PSP tente de débiter le compte du client avec le token de paiement stocké
3. Le PSP notifie Estaly du résultat de la tentative de paiement
4. Estaly met à jour le statut du contrat en fonction du résultat

Gestion des échecs de paiement

En cas d'échec de paiement, Estaly applique une stratégie de relance configurée dans votre back-office :

1. Première notification au client (email/SMS)
2. Nouvelle tentative de prélèvement après le délai configuré
3. En cas d'échecs répétés, notification au client et au marchand
4. Suspension potentielle du contrat après le nombre maximal de tentatives

4. Reporting et suivi

Dashboard marchand

Estaly fournit un dashboard marchand permettant de :

• Suivre l'état des souscriptions
• Visualiser les paiements réussis et échoués
• Gérer les réclamations et annulations
• Consulter les commissions générées

API de reporting

Une API REST est disponible pour intégrer les données de souscription et de paiement dans vos systèmes :

# Exemple de requête API pour obtenir le statut des paiements
curl -X GET "https://api.estaly.co/v1/merchant/payments" \
  -H "Authorization: Bearer {VOTRE_CLE_API}" \
  -H "Content-Type: application/json" \
  -d '{
    "start_date": "2025-03-01",
    "end_date": "2025-03-31"
  }'

5. Tests et validation

Environnement de test

Un environnement sandbox complet est disponible pour tester l'intégration :

1. URL de l'environnement sandbox : https://sandbox.estaly.co
2. Utilisez les identifiants de test fournis par votre gestionnaire de compte Estaly
3. Cartes de test pour le PSP :
   • Adyen : voir documentation des cartes de test Adyen
   • Stripe : voir documentation des cartes de test Stripe

Scénarios de test recommandés

Annexes

Dépannage