Système de Recharge et de Ravitaillement

Le système de recharge OmniCRM fournit un portail de recharge prépayé en libre-service pour que les clients ajoutent du crédit ou prolongent la validité du service via le Portail de Soins Autonomes. Cette fonctionnalité est couramment utilisée pour :

Services de données mobiles - Cartes SIM prépayées et services uniquement de données
Services de point d'accès - Dongles WiFi et dispositifs Internet portables
Services sans fil fixes - Accès Internet prépayé

Aperçu

Le système de recharge permet aux clients d'acheter des jours supplémentaires de service à travers un processus de paiement simplifié et en plusieurs étapes avec traitement de paiement intégré via Stripe.

Caractéristiques Clés :

Portail client en libre-service (aucune intervention du personnel requise)
Sélection de durée flexible (1-30 jours)
Affichage de l'utilisation en temps réel avant l'achat
Traitement de paiement sécurisé alimenté par Stripe
Remboursements automatiques si le ravitaillement échoue
Génération de factures et de transactions
Intégration du système de provisionnement pour l'activation du service

Accéder au Portail de Recharge

Le portail de recharge est accessible via une URL publique que les clients peuvent visiter sans se connecter au CRM :

Comment les Clients y Accèdent :

Lien direct envoyé par SMS lorsque le solde est bas
Code QR sur les documents imprimés
Lien sur le portail de soins autonomes
Partagé via le support client

Le portail détecte automatiquement le service du client en fonction de son adresse IP ou de son IMSI.

Processus de Recharge

Le flux de recharge se compose de 4 étapes :

Étape 1 : Sélection des Données

Les clients sélectionnent combien de jours de service ils souhaitent acheter.

Interface :

Contrôle de curseur - Sélectionnez de 1 à 30 jours
Calcul de prix en direct - Affiche le coût total basé sur la sélection
Affichage de la date d'expiration - Calcule et montre quand le service expirera
Affichage de l'utilisation actuelle - Montre le solde restant/l'expiration avant le ravitaillement

Exemple d'Affichage :

Configuration des Tarifs :

Le prix par jour est configuré via la variable d'environnement REACT_APP_TOPUP_PRICE_PER_DAY
Par défaut : $10 USD par jour
La devise est définie via REACT_APP_CURRENCY_CODE

Étape 2 : Informations de Facturation

Les clients fournissent leurs coordonnées pour la transaction :

Prénom
Nom de Famille
Adresse Email

Ces informations sont utilisées pour :

Génération de factures
Email de reçu de paiement
Enregistrements de transaction
Traitement des remboursements (si nécessaire)

Étape 3 : Paiement

Traitement de paiement sécurisé via Stripe Elements.

Méthodes de Paiement Supportées :

Cartes de crédit (Visa, Mastercard, Amex)
Cartes de débit
Portefeuilles numériques (Apple Pay, Google Pay) si activé dans Stripe

Fonctionnalités de Sécurité :

Intégration Stripe conforme PCI
Aucune donnée de carte stockée dans OmniCRM
Support d'authentification 3D Secure
Transmission de paiement cryptée

Flux de Paiement :

Formulaire Stripe Elements affiché avec saisie de carte
Le client saisit les détails de paiement
Intent de paiement créé pour le montant exact
Carte débitée immédiatement
Succès/échec du paiement géré

::: note ::: title Remarque :::

Si le paiement réussit mais que le provisionnement de la recharge échoue (par exemple, erreur réseau, OCS inaccessible), le système initie automatiquement un remboursement complet vers le mode de paiement du client. :::

Étape 4 : Finalisation

Écran de Succès :

Votre service a été prolongé. Nouvelle date d'expiration : 17 Jan 2025

Reçu envoyé à : <customer@example.com> ID de Transaction : TXN-123456

Écran d'Échec :

Si le ravitaillement échoue, le système affiche une erreur et traite automatiquement un remboursement :

Nous n'avons pas pu compléter votre ravitaillement. Votre paiement a été remboursé.

Erreur : Impossible de se connecter au système de facturation

Veuillez réessayer ou contacter le support.

Traitement Backend

Lorsque le client termine le paiement, les actions suivantes se produisent automatiquement :

1. Validation du Paiement

Le système valide :

Le statut de l'Intent de paiement est succeeded
Le montant du paiement correspond aux jours sélectionnés (days × price_per_day)
L'Intent de paiement n'a pas été traité auparavant (prévention des doubles recharges)

2. Opération de Recharge

- API endpoint: POST /oam/topup_dongle
- Valide service_uuid et IMSI
- Appelle OCS/CGRateS pour ajouter du solde
- Crée un job de provisionnement (play_topup_hotspot)

3. Création d'Enregistrements

Le système crée plusieurs enregistrements dans la base de données :

Enregistrement HotspotTopup - Suit la transaction de recharge
- payment_intent_id
- service_uuid
- imsi
- jours achetés
- topup_amount
- statut (Succès/Échoué/Remboursé)
Enregistrement de Transaction - Transaction financière
- Titre : "Recharge de Point d'Accès - 7 Jours"
- Montant : topup_amount (positif)
- Lié à service_id et customer_id
Enregistrement de Facture - Facture de paiement
- Contient la transaction de recharge
- Marqué comme payé immédiatement
- Référence de paiement : Stripe payment_intent_id
Transaction de Paiement - Transaction de crédit compensatoire
- Titre : "Paiement pour [Titre de la Facture]"
- Montant : topup_amount (négatif - crédit)
- Lie le paiement de la facture au compte client

4. Job de Provisionnement

Un job de provisionnement est créé avec le playbook play_topup_hotspot qui :

Se connecte à l'API OCS/CGRateS
Ajoute du solde au compte
Prolonge la date d'expiration
Crée une entrée dans le journal d'activité
Envoie une notification de confirmation (si configuré)

L'API attend que le provisionnement soit terminé (polling avec des intervalles de 0,2s, max 25 itérations) avant de retourner le succès au client.

5. Remboursement Automatique en Cas d'Échec

Si une étape échoue après le paiement :

if topup_provisioning_failed:
    refund = stripe.Refund.create(
        payment_intent=payment_intent_id,
        reason='requested_by_customer'  # Remboursement automatique du système
    )
    status_message = "Échec du Ravitaillment. Remboursement du paiement..."

Le remboursement est traité automatiquement et le client est notifié à l'écran.

Points de Terminaison API

Point de Terminaison de Recharge

POST /oam/topup_dongle
Content-Type: application/json

{
  "service_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "imsi": "310120123456789",
  "days": 7,
  "payment_intent_id": "pi_1234567890abcdef",
  "topup_amount": 70.00
}

Réponse (Succès) :

{
  "result": "OK",
  "status": 200,
  "provision_id": 456,
  "payment_intent_id": "pi_1234567890abcdef",
  "service_uuid": "123e4567-e89b-12d3-a456-426614174000",
  "invoice_id": 789
}

Réponse (Échec) :

{
  "result": "Failed",
  "Reason": "Délai d'attente de connexion OCS",
  "status": 500
}

Vérifications de Validation :

Tous les champs requis présents (service_uuid, imsi, days, payment_intent_id, topup_amount)
topup_amount correspond aux jours : topup_amount × 100 == days × 1000 (en cents)
L'Intent de paiement existe dans Stripe
Le montant de l'Intent de paiement correspond : payment_intent.amount == topup_amount × 100
Le statut de l'Intent de paiement est succeeded
L'Intent de paiement n'a pas déjà été traité (vérifie la table HotspotTopup)

Point de Terminaison d'Utilisation

Récupère l'utilisation actuelle et les informations de service pour le client :

GET /oam/usage

Réponse :

{
  "imsi": "310120123456789",
  "service": {
    "service_uuid": "123e4567-e89b-12d3-a456-426614174000",
    "service_name": "Données Mobiles - 0412345678",
    "service_status": "Actif"
  },
  "balance": {
    "expiry": "2025-01-10T23:59:59Z",
    "unlimited": true
  },
  "requestingIp": "203.0.113.45"
}

Ce point de terminaison utilise l'adresse IP de demande pour identifier automatiquement le service du client.

Configuration

Variables d'Environnement

Configurez ceci dans le fichier .env d'OmniCRM-UI :

# Configuration du Portail de Recharge
REACT_APP_TOPUP_PRICE_PER_DAY=10
REACT_APP_CURRENCY_CODE=AUD
REACT_APP_SELF_CARE_NAME="VotreEntreprise"

# Configuration de Stripe
REACT_APP_STRIPE_PUBLISHABLE_KEY=pk_live_...

Configuration de Stripe

Le système de recharge utilise les Intents de Paiement Stripe :

Activer les Intents de Paiement dans votre tableau de bord Stripe
Configurer le Webhook pour recevoir des mises à jour de statut de paiement (optionnel mais recommandé)
Configurer les méthodes de paiement (cartes, portefeuilles, etc.)
Mode test - Utilisez des clés de test pour le développement

# Développement
REACT_APP_STRIPE_PUBLISHABLE_KEY=pk_test_...

# Production
REACT_APP_STRIPE_PUBLISHABLE_KEY=pk_live_...

Configuration du Playbook

Le playbook de provisionnement play_topup_hotspot.yaml doit être configuré pour :

Accepter la variable days
Se connecter à l'API OCS/CGRateS
Ajouter du solde au compte
Mettre à jour la date d'expiration du service

Exemple de structure de playbook :

- name: Ravitaillement du service de point d'accès
  hosts: localhost
  tasks:
    - name: Ajouter du solde à OCS
      uri:
        url: "{{ ocs_api_url }}/add_balance"
        method: POST
        body:
          imsi: "{{ imsi }}"
          days: "{{ days }}"
          service_uuid: "{{ service_uuid }}"

Notifications de Solde Bas

Le système peut envoyer des notifications automatiques lorsque le solde du client est bas :

Notifications par SMS :

Lorsqu'elles sont déclenchées par des événements OCS (Action_Balance_Low, Action_Balance_Out, Action_Balance_Expired) :

Notifications par Email :

Configurées dans les plans d'action OCS/CGRateS pour envoyer des alertes de solde.

Déclencheurs de Notification :

Action_Balance_Low - Solde en dessous du seuil (par exemple, 2 jours restants)
Action_Balance_Out - Solde épuisé
Action_Balance_Expired - Service expiré

Chaque notification inclut le lien du portail de recharge pour un accès facile des clients.

Dépannage

Problèmes Courants

"Système de paiement indisponible"

Cause : La bibliothèque Stripe n'a pas pu se charger ou clé publique invalide
Solution :
- Vérifiez que REACT_APP_STRIPE_PUBLISHABLE_KEY est correctement défini
- Vérifiez que le compte Stripe est actif
- Vérifiez la console du navigateur pour des erreurs JavaScript

"Échec du ravitaillement. Remboursement du paiement..."

Cause : Échec du job de provisionnement (OCS inaccessible, erreur de playbook, etc.)
Solution :
- Vérifiez les journaux de provisionnement : GET /crm/provision/provision_id/<id>
- Vérifiez que l'API OCS/CGRateS est accessible
- Passez en revue le playbook play_topup_hotspot.yaml pour des erreurs
- Vérifiez les journaux Ansible

"Intent de paiement déjà traité"

Cause : Le client tente de réutiliser le même paiement (par exemple, actualiser après le succès)
Solution : Cela fonctionne comme prévu pour éviter la double facturation. Le client doit commencer un nouveau ravitaillement si nécessaire.

"Le montant de l'intent de paiement ne correspond pas"

Cause : Mismatch entre le calcul de l'UI et la validation backend
Solution :
- Vérifiez que REACT_APP_TOPUP_PRICE_PER_DAY correspond à l'attente backend (par défaut $10)
- Vérifiez que la configuration de la devise est cohérente
- Effacez le cache du navigateur et réessayez

Surveillance des Recharges

Voir les Enregistrements de Recharge :

Interrogez la table HotspotTopup pour voir toutes les tentatives de recharge :

SELECT
  hotspot_topup_id,
  service_uuid,
  days,
  topup_amount,
  status,
  payment_intent_id,
  created
FROM hotspot_topup
WHERE status = 'Failed'
ORDER BY created DESC;

Vérifiez le Statut de Provisionnement :

GET /crm/provision/provision_id/<provision_id>

Affiche le statut détaillé du job de provisionnement de recharge.

Tableau de Bord Stripe :

Surveillez les paiements, remboursements et transactions échouées dans votre tableau de bord Stripe à <https://dashboard.stripe.com>

Considérations de Sécurité

Sécurité des Paiements :

Toutes les données de carte gérées par Stripe (conforme PCI Niveau 1)
Aucune donnée de paiement sensible stockée dans la base de données OmniCRM
Les Intents de paiement empêchent les charges non autorisées
Validation des montants des deux côtés, client et serveur

Prévention de la Fraude :

La détection des Intents de paiement en double empêche la double facturation
Suivi de l'adresse IP pour la corrélation d'utilisation
La validation de l'IMSI garantit que le ravitaillement va au bon service
Les remboursements automatiques limitent l'exposition financière

Contrôle d'Accès :

Le portail de recharge est public (par conception - les clients ont besoin d'accès)
Le point de terminaison d'utilisation nécessite une identification de service valide (IP ou IMSI)
La validation backend empêche les recharges de service arbitraires
L'administrateur peut voir tous les enregistrements de recharge via l'interface CRM

Meilleures Pratiques

Pour les Opérateurs :

Tester le flux de remboursement - Testez régulièrement les scénarios d'échec pour vous assurer que les remboursements fonctionnent
Surveiller les recharges échouées - Configurez des alertes pour des taux d'échec élevés
Garder les playbooks simples - Les playbooks de recharge doivent être rapides et fiables
Vérifier la connectivité OCS - Assurez-vous que l'API OCS est toujours accessible
Revoir les prix - Mettez à jour REACT_APP_TOPUP_PRICE_PER_DAY si nécessaire

Pour les Clients :

Ajouter l'URL de recharge aux favoris - Accès rapide en cas de besoin
Conserver les notifications de solde bas - Le SMS contient un lien direct
Maintenir l'email à jour - Les reçus sont envoyés à l'email enregistré
Vérifier l'expiration avant de voyager - Rechargez avant de quitter la zone de couverture

Pour les Développeurs :

Gérer les webhooks Stripe - Implémentez des gestionnaires de webhook pour les mises à jour de statut de paiement
Implémenter l'idempotence - Vérifiez toujours payment_intent_id avant de traiter
Logger de manière extensive - Les échecs de recharge nécessitent des informations de dépannage détaillées
Tester les chemins d'erreur - Vérifiez que l'automatisation des remboursements fonctionne correctement
Surveiller les performances - Le polling de provisionnement doit se terminer en <5 secondes

Documentation Connexe

payments_process - Traitement général des paiements
concepts_provisioning - Aperçu du système de provisionnement
integrations_stripe - Détails de l'intégration Stripe
payments_transaction - Gestion des transactions
payments_invoices - Gestion des factures

Aperçu​

Accéder au Portail de Recharge​

Processus de Recharge​

Étape 1 : Sélection des Données​

Étape 2 : Informations de Facturation​

Étape 3 : Paiement​

Étape 4 : Finalisation​

Traitement Backend​

Points de Terminaison API​

Point de Terminaison de Recharge​

Point de Terminaison d'Utilisation​

Configuration​

Variables d'Environnement​

Configuration de Stripe​

Configuration du Playbook​

Notifications de Solde Bas​

Dépannage​

Problèmes Courants​

Surveillance des Recharges​

Considérations de Sécurité​

Meilleures Pratiques​

Documentation Connexe​