Intégration de paiements récurrents avec Viva Wallet : Guide complet pour les développeurs

Dans un monde où les modèles économiques par abonnement sont devenus incontournables, la mise en place d'un système de paiement récurrent fiable et sécurisé représente un enjeu majeur pour de nombreuses entreprises. Chez Platane, nous accompagnons régulièrement nos clients dans l'implémentation de solutions de paiement adaptées à leurs besoins spécifiques. Aujourd'hui, nous souhaitons partager notre expertise sur l'intégration de Viva Wallet Smart Checkout pour les paiements récurrents.

Pourquoi choisir Viva Wallet pour les paiements récurrents ?

Viva Wallet s'est imposé comme une solution de paiement européenne robuste, offrant une alternative intéressante aux acteurs traditionnels comme Stripe ou PayPal. Parmi ses avantages :

• Frais compétitifs par rapport aux autres solutions du marché
• Conformité RGPD et hébergement des données en Europe
• API complète permettant une grande flexibilité d'intégration
• Smart Checkout : une solution clé en main qui simplifie la gestion des paiements
• Support des paiements récurrents avec une architecture sécurisée

Architecture technique pour l'intégration de paiements récurrents

L'implémentation d'un système de paiement récurrent avec Viva Wallet nécessite une architecture backend solide. Voici comment nous structurons généralement ce type de projet :

1. Mise en place du backend

Pour une intégration optimale, nous recommandons l'utilisation de Node.js avec un framework comme Express ou NestJS. Cette stack offre plusieurs avantages :

• Performance : Node.js excelle dans la gestion des opérations I/O asynchrones
• Écosystème riche de bibliothèques pour l'intégration avec les API de paiement
• Facilité de déploiement sur différentes infrastructures cloud

// Exemple simplifié d'initialisation d'un serveur Express pour l'intégration Viva Wallet
const express = require('express');
const bodyParser = require('body-parser');
const axios = require('axios');
const crypto = require('crypto');

const app = express();
app.use(bodyParser.json());

// Configuration des clés d'API Viva Wallet
const VIVA_CLIENT_ID = process.env.VIVA_CLIENT_ID;
const VIVA_CLIENT_SECRET = process.env.VIVA_CLIENT_SECRET;
const VIVA_API_URL = process.env.VIVA_API_URL; // Sandbox ou Production

// Routes pour l'intégration à définir...

app.listen(3000, () => {
  console.log('Serveur démarré sur le port 3000');
});

2. Création d'une commande avec paiement récurrent

La première étape consiste à créer une commande via l'API Viva Wallet en spécifiant l'option allowRecurring: true. Cette configuration est essentielle pour permettre les débits ultérieurs sans nouvelle authentification du client.

app.post('/api/create-subscription', async (req, res) => {
  try {
    // Authentification auprès de Viva Wallet pour obtenir un token
    const authResponse = await axios.post(
      `${VIVA_API_URL}/connect/token`,
      'grant_type=client_credentials',
      {
        headers: {
          'Content-Type': 'application/x-www-form-urlencoded',
          'Authorization': `Basic ${Buffer.from(`${VIVA_CLIENT_ID}:${VIVA_CLIENT_SECRET}`).toString('base64')}`
        }
      }
    );
    
    const accessToken = authResponse.data.access_token;
    
    // Création de la commande avec option de récurrence
    const orderResponse = await axios.post(
      `${VIVA_API_URL}/checkout/v2/orders`,
      {
        amount: req.body.amount * 100, // Montant en centimes
        customerTrns: req.body.description,
        customer: {
          email: req.body.email,
          fullName: req.body.fullName,
        },
        paymentTimeout: 1800,
        allowRecurring: true, // Activation du paiement récurrent
        merchantTrns: generateUniqueReference(), // Référence unique
        sourceCode: process.env.VIVA_SOURCE_CODE
      },
      {
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'Content-Type': 'application/json'
        }
      }
    );
    
    // Retourne l'URL de paiement et l'orderCode
    res.json({
      checkoutUrl: orderResponse.data.checkoutUrl,
      orderCode: orderResponse.data.orderCode
    });
  } catch (error) {
    console.error('Erreur lors de la création de la commande:', error);
    res.status(500).json({ error: 'Erreur lors de la création de la commande' });
  }
});

function generateUniqueReference() {
  return `SUB-${Date.now()}-${crypto.randomBytes(4).toString('hex')}`;
}

3. Configuration des webhooks pour le suivi des paiements

Les webhooks sont essentiels pour recevoir les notifications de paiement en temps réel. Ils permettent de mettre à jour le statut des abonnements et de déclencher les actions appropriées.

app.post('/webhooks/viva-wallet', async (req, res) => {
  // Vérification de la signature du webhook (recommandé)
  if (!verifyWebhookSignature(req)) {
    return res.status(401).send('Signature invalide');
  }
  
  const eventData = req.body;
  
  // Traitement selon le type d'événement
  switch (eventData.eventTypeId) {
    case 'transaction.created':
      // Paiement initial réussi
      const transactionId = eventData.transactionId;
      
      // Enregistrer l'ID de transaction pour les paiements récurrents futurs
      await saveTransactionForRecurring(
        eventData.orderCode,
        transactionId,
        eventData.customerEmail
      );
      
      // Activer l'abonnement dans votre système
      await activateSubscription(eventData.orderCode);
      break;
      
    case 'transaction.failed':
      // Gestion des échecs de paiement
      await handleFailedPayment(eventData.orderCode);
      break;
      
    // Autres cas à gérer...
  }
  
  res.status(200).send('Webhook reçu');
});

4. Implémentation des paiements récurrents automatisés

Pour les paiements suivants, vous devrez mettre en place un système de tâches planifiées (cron jobs) qui déclenchera les paiements à la fréquence souhaitée.

// Fonction appelée par un cron job pour traiter les paiements récurrents
async function processRecurringPayments() {
  // Récupérer les abonnements à débiter aujourd'hui
  const subscriptionsDue = await getSubscriptionsDueToday();
  
  for (const subscription of subscriptionsDue) {
    try {
      // Authentification auprès de Viva Wallet
      const accessToken = await getVivaWalletToken();
      
      // Création d'un paiement récurrent en utilisant l'ID de transaction initial
      const recurringPaymentResponse = await axios.post(
        `${VIVA_API_URL}/checkout/v2/transactions/${subscription.initialTransactionId}/recurring`,
        {
          amount: subscription.amount * 100, // Montant en centimes
          merchantTrns: `Recurring-${subscription.id}-${Date.now()}`,
          customerTrns: `Abonnement mensuel - ${subscription.reference}`
        },
        {
          headers: {
            'Authorization': `Bearer ${accessToken}`,
            'Content-Type': 'application/json'
          }
        }
      );
      
      // Mise à jour du statut de l'abonnement
      await updateSubscriptionPaymentStatus(
        subscription.id,
        'success',
        recurringPaymentResponse.data.transactionId
      );
      
    } catch (error) {
      console.error(`Échec du paiement récurrent pour l'abonnement ${subscription.id}:`, error);
      
      // Gestion des erreurs (notification client, nouvelle tentative, etc.)
      await handleRecurringPaymentFailure(subscription, error);
    }
  }
}

Bonnes pratiques de sécurité

La sécurité est primordiale lorsqu'il s'agit de traiter des paiements. Voici les mesures que nous mettons systématiquement en place chez Platane :

1. Protection des données sensibles

• Aucun stockage de données de carte sur vos serveurs (conformité PCI-DSS)
• Chiffrement des identifiants de transaction stockés pour les paiements récurrents
• Variables d'environnement pour les clés d'API et secrets
• Rotation régulière des clés d'API

2. Sécurisation des communications

• HTTPS obligatoire pour toutes les communications
• Validation des signatures des webhooks
• Rate limiting pour prévenir les attaques par force brute
• Journalisation sécurisée des événements de paiement (sans données sensibles)

3. Gestion des erreurs

Un système robuste de gestion des erreurs est essentiel pour maintenir une bonne expérience utilisateur et assurer la continuité des revenus :

• Notifications automatiques en cas d'échec de paiement
• Tentatives multiples pour les paiements échoués
• Communication proactive avec les clients en cas de problème de paiement
• Tableau de bord administrateur pour suivre et gérer les exceptions

Retour d'expérience : cas concrets d'intégration

Chez Platane, nous avons eu l'occasion de mettre en œuvre cette architecture pour plusieurs clients avec des besoins variés. Par exemple :

• Pour Easop, une plateforme de gestion de stock options, nous avons intégré un système de paiement récurrent pour les abonnements premium, générant des revenus prévisibles et stables. La stack technique (NextJS, TypeScript, PostgreSQL) a permis une intégration fluide avec Stripe, suivant des principes similaires à ceux décrits pour Viva Wallet.

• Pour Dealt, une marketplace de services, nous avons développé une architecture de paiement sécurisée permettant des transactions ponctuelles mais aussi des abonnements récurrents. L'utilisation de Node.js avec Docker et AWS a offert une solution scalable et robuste.

• Pour Epictory, nous avons mis en place un système de génération de posters basés sur des parcours Strava, incluant une option d'abonnement pour les utilisateurs réguliers. L'architecture backend a été conçue pour gérer efficacement les paiements récurrents tout en maintenant une expérience utilisateur fluide.

Tests et déploiement

Avant de passer en production, il est crucial de tester exhaustivement l'intégration :

1. Tests en environnement sandbox de Viva Wallet
2. Tests unitaires pour chaque composant du système de paiement
3. Tests d'intégration simulant le parcours complet
4. Tests de charge pour vérifier la robustesse du système

Pour le déploiement, nous recommandons une approche progressive :

1. Configuration duale (sandbox/production) avec bascule simple
2. Déploiement par phases avec surveillance accrue
3. Rollback automatisé en cas de problème détecté

Conclusion

L'intégration de paiements récurrents avec Viva Wallet Smart Checkout représente un investissement technique significatif, mais offre un retour sur investissement considérable pour les entreprises souhaitant développer un modèle économique basé sur l'abonnement.

La clé du succès réside dans une architecture backend solide, une sécurité irréprochable et une gestion efficace des cas d'erreur. Chez Platane, nous avons développé une expertise pointue dans ce domaine, permettant à nos clients de bénéficier d'une solution sur mesure, adaptée à leurs besoins spécifiques.

Vous avez un projet nécessitant l'intégration de paiements récurrents ou souhaitez optimiser votre système actuel ? N'hésitez pas à prendre rendez-vous via notre formulaire de contact. Notre équipe d'experts se fera un plaisir d'échanger avec vous sur votre projet et de vous proposer une solution adaptée à vos objectifs. Collaborer avec Platane, c'est bénéficier d'une expertise technique de pointe et d'un accompagnement personnalisé tout au long de votre projet.