Paiements FeexPay

Vue d'ensemble

Tranoo utilise FeexPay comme agrégateur de paiement pour Mobile Money (MTN, Moov, Orange) et cartes bancaires. L'intégration couvre le backend Express, les apps Flutter et le dashboard web.

Architecture

┌─────────────┐     init paiement      ┌──────────────┐
│ Flutter /   │ ─────────────────────► │  API Express │
│ Dashboard   │                        │ paymentCtrl  │
└─────────────┘                        └──────┬───────┘
                                              │
                    ┌─────────────────────────┼─────────────────────────┐
                    ▼                         ▼                         ▼
             ┌────────────┐           ┌────────────┐           ┌────────────┐
             │  FeexPay   │           │  MongoDB   │           │  Webhook   │
             │  API v2    │           │  Payment   │           │  callback  │
             └────────────┘           └────────────┘           └────────────┘

Modèle de données

Payment.js — collection des transactions

Champ	Description
userId	Utilisateur payeur
montant	Montant en XOF
reference	Référence FeexPay
statut	pending, success, failed, expired
type	achat, abonnement, publicite, verification, etc.
metadata	Contexte métier (articleId, subscriptionId…)

Endpoints principaux

Préfixe : /api/payments

Méthode	Route	Auth	Description
POST	/init	Oui	Initialise un paiement
POST	/requesttopay/:network	Oui	Mobile Money (MTN, Moov…)
POST	/initcard	Oui	Paiement carte
POST	/webhook	Non	Callback serveur FeexPay
GET	/public/status/:id	Non	Statut public transaction
POST	/flutter/record	Oui	Enregistrement post-paiement Flutter
GET	/:id	Oui	Détail paiement
POST	/admin/:id/status	Admin	Mise à jour statut manuelle

Variables d'environnement

Variable	Description
FEEXPAY_BASE_URL	URL API FeexPay
FEEXPAY_FEEXLINK_BASE_URL	URL FeexLink (lien de paiement)
FEEXPAY_SHOP_ID	Identifiant boutique
FEEXPAY_API_TOKEN	Token API
FEEXPAY_MODE	SANDBOX ou LIVE
PAYMENT_EXPIRE_SECONDS	Expiration transaction
FEEXLINK_DISABLED	Désactiver FeexLink
FEEXPAY_DISABLE_LOCAL_EXPIRY	Désactiver expiration locale

Flux de paiement

1. Initialisation (mobile ou web)

1. Client appelle POST /api/payments/init avec montant et type
2. Backend crée un document Payment (statut pending)
3. Backend appelle FeexPay et retourne URL ou données de paiement

2. Paiement utilisateur

• Mobile Money : l'utilisateur valide sur son téléphone
• Carte : redirection vers page FeexPay
• Flutter : SDK feexpay_flutter_v2 ouvre le flux natif

3. Confirmation

1. FeexPay envoie un webhook à POST /api/payments/webhook
2. Backend met à jour le statut Payment
3. Actions métier déclenchées (activation abonnement, validation publicité, etc.)

4. Worker de suivi

paymentController.startPaymentStatusWorker() — polling des paiements en attente au démarrage du serveur.

Wallet (portefeuille)

Préfixe : /api/wallet (auth requis)

Route	Description
GET /me	Solde et infos wallet
GET /me/transactions	Historique transactions
GET /me/stats	Statistiques wallet

Utilisé principalement par Tranoo Pro (vendeurs). Le wallet livreur fait partie du système legacy (voir Intégration Livro).

Intégration Flutter

Fichiers de référence :

• tranoo/lib/config/feexpay_config.dart
• tranoo_pro/lib/config/feexpay_config.dart
• tranoo/FEEXPAY_INTEGRATION.md (guide détaillé dans le dépôt)

// Exemple simplifié
final result = await FeexPayService.startPayment(
  amount: 5000,
  customId: "CMD_001",
  description: "Paiement commande",
  paymentType: "MOBILE",
);

Types de paiement métier

Type	Déclencheur	Effet
Abonnement vendeur	subscription_payment.dart	Active Subscription
Abonnement transitaire	Tranoo Pro	Active abonnement transitaire
Publicité	Boost article	Active Publicite
Vérification article	Acheteur	Lance vérification
Achat	Commande	Met à jour Order / Achat

Sécurité

• Webhook FeexPay : endpoint public (pas de Bearer) — validation côté FeexPay
• Paiements utilisateur : authMiddleware requis
• Admin : role.js pour modification manuelle statut
• Expiration automatique via PAYMENT_EXPIRE_SECONDS

Scripts de maintenance

npm run cleanup:vehicle-payments   # Nettoyage paiements véhicules

Voir aussi

• Architecture Backend
• API Swagger — domaine 06-payments-wallet.js
• Déploiement — variables FeexPay