Tableau de bord marchand

Le Tableau de bord marchand Xaalis (/dashboard/*) permet aux marchands et à leurs équipes de suivre les soldes, gérer les paiements et virements, administrer les abonnements et factures, configurer les webhooks, effectuer la rotation des clés d’API et gérer les membres de l’équipe.

Authentification et accès

L’accès au tableau de bord s’effectue sans mot de passe et uniquement sur invitation :

1. Aucune inscription publique : Les utilisateurs du tableau de bord sont configurés par un opérateur (via POST /admin/merchants/{id}/dashboard-memberships) ou invités par un Propriétaire (Owner) existant.
2. Liens magiques (Magic Links) : Connectez-vous en saisissant votre adresse e-mail sur /dashboard/login. Vous recevez immédiatement un lien de connexion sécurisé (POST /dashboard/auth/sign-in/magic-link).
3. Cookie de session : Cliquer sur le lien reçu dans l’e-mail établit un cookie de session sécurisé HttpOnly (credentials: "include"). Aucun jeton ou secret n’est conservé dans le stockage du navigateur (localStorage ou sessionStorage).

Rôles et autorisations

Chaque collaborateur dispose d’un rôle spécifique attribué sur le compte marchand :

Fonctionnalité / Action	Propriétaire	Développeur	Lecteur
Consulter les soldes, transactions et factures	✓	✓	✓
Consulter les livraisons de webhooks et payloads	✓	✓	✓
Créer des paiements test et simuler les résultats	✓	✓	—
Créer des abonnements et avancer les cycles (test)	✓	✓	—
Initier des virements (réels ou test)	✓	—	—
Résilier des abonnements (immédiat ou fin de période)	✓	—	—
Gérer les clés d’API (créer, renouveler, révoquer)	✓	—	—
Modifier l’URL de webhook en direct	✓	—	—
Inviter ou retirer des membres de l’équipe	✓	—	—

Mode Test vs Mode En direct

La barre de navigation supérieure intègre un sélecteur visible entre le Mode Test et le Mode En direct :

• En Mode Test, un bandeau d’avertissement ambre de 32px s’affiche au sommet de l’interface. Toutes les données, transactions et soldes affichés proviennent strictement du grand livre test:.
• Les actions exécutées en Mode Test (création de paiements test, simulation de validations ou d’échecs, rotation de clés test) ne touchent jamais à de l’argent réel ni aux opérateurs télécoms réels.
• Vous pouvez basculer d’un mode à l’autre en un clic ; vos permissions restent identiques.

Solde et Virements

Bandeau de solde

Le tableau de bord met en avant deux montants consolidés :

• Disponible : Fonds encaissés et disponibles sur votre compte marchand, prêts pour un virement immédiat.
• Virements en cours : Fonds réservés pour des virements en cours de traitement vers Wave ou Orange Money.

Initier un virement (Payout)

1. Cliquez sur Virer les fonds depuis le bandeau de solde ou la page Virements.
2. Choisissez l’opérateur bénéficiaire (Wave ou Orange Money).
3. Renseignez le numéro de téléphone mobile au format sénégalais normalisé : +2217XXXXXXXX.
4. Indiquez le montant en nombre entier de FCFA (qui doit être $\le$ Disponible déduction faite des frais fixes de virement payout_fee_fixed retournés par /balance, plafonné à 100 000 000 FCFA). Le bouton Max calcule automatiquement Math.max(0, available - payout_fee_fixed).
5. Vérifiez le récapitulatif exact — montant envoyé au bénéficiaire, frais fixes de virement Xaalis (payout_fee_fixed) et total débité du solde (amount + payout_fee_fixed) — après rafraîchissement automatique du solde avant confirmation.
6. L’opération transmet un en-tête Idempotency-Key unique et automatique pour garantir l’absence de doublon.

Paiements et simulation test

• Historique en temps réel : Tableau affichant la date, les coordonnées client, la référence de commande, la référence reçu opérateur (provider_transaction_id), le montant brut et les frais prélevés.
• Filtres par statut et reçu opérateur (WA-5) : Filtrez rapidement par succeeded, processing, requires_payment_method, failed ou expired, ou recherchez directement par référence reçu opérateur (provider_transaction_id, ex. T_M6MTZ6GXKQ4YDFTP) pour rapprocher une capture d’écran client.
• Tiroir de détail : Cliquez sur n’importe quel paiement pour déployer le panneau latéral complet affichant l’identifiant exact Xaalis, le détail des frais, le montant net et le lien direct vers le checkout hébergé.
• Simulation : En Mode Test, un paiement en attente ou en cours de traitement peut être simulé en succeeded ou failed directement depuis le tiroir afin de tester vos webhooks.

Abonnements et Factures

La section Abonnements permet la gestion de la facturation récurrente :

• Création d’abonnements : Définition de forfaits avec fréquence (hebdomadaire, mensuelle, trimestrielle, semestrielle, annuelle), nombre de cycles, informations client et délai d’échéance (days_until_due).
• Factures : Chaque cycle génère une facture dotée d’un lien de paiement client dédié (hosted_invoice_url). Statuts disponibles : brouillon, ouverte, payée, en retard ou irrécouvrable.
• Résiliation :
  • À la fin de la période (at_period_end: true) : La période en cours reste active et payable ; aucun renouvellement futur n’aura lieu.
  • Immédiate (at_period_end: false) : Annulation immédiate. Si un paiement est déjà en cours de traitement chez l’opérateur, il sera régularisé proprement sans facturation ultérieure.
• Avancement de cycle en test : Les développeurs peuvent forcer l’avancement immédiat d’un cycle en mode test pour valider les renouvellements et l’émission des factures.

Espace Développeurs et Sécurité

Accessible via /dashboard/developers, cet espace est dédié aux intégrations techniques :

Clés d’API

• Liste des clés actives et planifiées pour révocation selon le mode sélectionné.
• Seuls les identifiants techniques sûrs (key_...), le préfixe affiché (sk_test_... ou sk_live_...) et la date de création sont consultables.
• Génération de clé : La clé secrète n’est révélée qu’une seule fois dans une fenêtre modale sécurisée avec bouton de copie. Elle n’est jamais stockée dans le navigateur ni récupérable par l’API ultérieurement.
• Renouvellement sans coupure (Roll) : Permet de configurer un délai de grâce entre 1 et 72 heures (24h par défaut). L’ancienne clé reste valide jusqu’à l’heure programmée (scheduled_revoke_at), laissant le temps de mettre à jour vos serveurs de production.
• Révocation immédiate : Pour révoquer sans délai une clé compromise.

Webhooks et destinations multiples

Accessible sous /dashboard/developers?tab=webhooks, la gestion des webhooks prend en charge :

• Endpoint principal et destinations multiples (WA-1) : Chaque compte dispose d’un endpoint par défaut ainsi que jusqu’à 9 destinations personnalisées par mode (test ou live).
• Filtrage fin des événements : Vous pouvez cibler précisément les types d’événements attendus par chaque destination (payment.succeeded, payment.failed, payout.succeeded, invoice.paid, etc.).
• Politique de confidentialité des données (Payload Policy) :
  • full : Envoie l’objet ressource complet.
  • minimal : Envoie uniquement l’identifiant de l’événement, le type de ressource et son identifiant technique (pour contraindre le récepteur à re-valider la ressource via l’API authentifiée).
• Secret de signature dédié : Chaque destination génère son propre secret de signature (whsec_...) révélé une seule fois à la création.
• Endpoints gérés automatiquement (WA-1b) : Les endpoints liés au service WhatsApp portent la mention Géré automatiquement (managed_by: "whatsapp") et sont protégés contre toute modification ou suppression accidentelle.

Assistant WhatsApp Marchand et Virements Sécurisés

Accessible sous /dashboard/settings?tab=whatsapp, cette fonctionnalité permet de piloter votre boutique directement depuis WhatsApp :

Liaison de compte (WA-2)

• Chaque membre peut lier son numéro sénégalais (+221…) en générant un code unique à 8 caractères valable 10 minutes.
• Une fois le code envoyé sur WhatsApp, le membre doit approuver la liaison sur le tableau de bord pour l’activer.
• Vous pouvez activer ou désactiver les notifications de paiement reçu en temps réel (notifications.payment_succeeded).
• Les propriétaires visualisent l’ensemble des liaisons de l’organisation ; les collaborateurs gèrent uniquement la leur.

Virements WhatsApp et sécurité PIN (WA-3, WA-3b)

Les propriétaires de boutique peuvent initier des virements rapides sur WhatsApp en toute sécurité financière :

• Validation par code PIN à 6 chiffres : La confirmation s’effectue exclusivement sur une page Web sécurisée Xaalis (/wa/pin/[token]), jamais dans la conversation de chat.
• Protection cryptographique : Le code PIN est haché avec Argon2id et combiné à un poivre applicatif sécurisé (WHATSAPP_PIN_PEPPER).
• Verrouillage automatique : 3 tentatives erronées entraînent le verrouillage immédiat du service pour 24 heures.
• Délai de sécurité de 24h : Tout nouveau compte lié, réinitialisation de PIN, déverrouillage ou augmentation du plafond quotidien est soumis à une période de grâce incompressible de 24 heures.
• Plafond quotidien : Plafond journalier configurable (en XOF) réinitialisé à minuit heure de Dakar.
• Destination vérifiée : Les virements WhatsApp sont strictement limités au compte de règlement validé lors de l’onboarding (Wave).
• Lien à usage unique de 5 minutes : Le lien de saisie du PIN expire au bout de 5 minutes et ne peut être réutilisé après validation.

Raccourcis Clavier et Ergonomie Opérateur

Le tableau de bord est entièrement optimisé pour les opérateurs grâce à des raccourcis clavier rapides :

Navigation globale

• ⌘K / Ctrl+K : Ouvrir la palette de commandes universelle pour rechercher une page ou exécuter une action.
• ? : Afficher la fenêtre d’aide avec tous les raccourcis disponibles.
• m : Basculer instantanément entre le Mode Test et le Mode En direct.
• Enchaînements de navigation (g puis…) :
  • g puis h : Vue d’ensemble (Accueil)
  • g puis p : Paiements & Transactions
  • g puis s : Abonnements & Factures
  • g puis o : Virements (Payouts)
  • g puis a : Portefeuilles d’Agents IA
  • g puis d : Espace Développeurs
  • g puis t : Paramètres du compte

Navigation dans les tableaux et listes

• j / ↓ : Sélectionner la ligne suivante.
• k / ↑ : Sélectionner la ligne précédente.
• Entrée : Ouvrir le tiroir de détail de la transaction ou de l’élément sélectionné.
• c : Copier l’identifiant technique (pay_..., po_..., sub_...) dans le presse-papiers.
• r : Actualiser les données de la page courante en direct.
• e : Exporter la liste affichée au format CSV.
• / : Placer immédiatement le curseur dans le champ de recherche.
• 1, 2, 3… : Basculer entre sous-onglets dans Développeurs, Abonnements et Paramètres.

Remboursements de paiements

Les Propriétaires du compte peuvent initier le remboursement intégral d’une transaction depuis /dashboard/payments ou le tiroir de détail :

• Éligibilité : Actuellement disponible pour les paiements réussis encaissés via Wave.
• Débit du montant brut : Le remboursement débite l’intégralité du montant brut initial sur le solde disponible marchand. La politique standard de frais Xaalis s’applique.
• Fonds insuffisants (422) : Si le solde disponible est inférieur au montant brut à rembourser, le tableau de bord indique clairement la nécessité d’encaisser de nouveaux paiements ou d’approvisionner le compte avant de réitérer.
• Clés d’idempotence liées par paiement (R-2) : L’en-tête Idempotency-Key d’un remboursement est isolé par (merchantId, mode, paymentId) et conservé en cas de reprise réseau ; la réutilisation d’une même clé sur un autre paiement renvoie 409 idempotency_conflict.
• Statuts durables : Le résultat du remboursement est suivi de façon vérifiable (pending, needs_review ou succeeded). Un remboursement réussi met immédiatement à jour le statut du paiement en refunded.

Portefeuilles d’Agents IA Autonomes

Accessible sous /dashboard/agent-wallets, cet espace réservé aux Propriétaires permet de déléguer des budgets contrôlés à des agents d’intelligence artificielle ou scripts autonomes :

• Sous-portefeuilles dédiés : Chaque agent dispose d’un solde isolé sur le grand livre et d’une politique de dépenses stricte.
• Plafond quotidien (max_daily_amount) : Limite de dépenses journalières calculée sur le fuseau horaire Africa/Dakar et réinitialisée automatiquement à minuit.
• Approbation propriétaire hors-plafond (AW-10, Mode Test) : En Mode Test, le propriétaire peut activer approval_above_limit avec un plafond maximal approval_max_amount ($\ge$ max_payout_amount). Lorsqu’un agent initie un virement dépassant max_payout_amount ou max_daily_amount (dans la limite de approval_max_amount), l’API retourne 202 Accepted (agent_payout_approval, status: "pending") sans bloquer ni réserver les fonds tant que le propriétaire n’a pas approuvé la demande et validé son code PIN à 6 chiffres sur /wa/pin/[token]?purpose=agent_approval. Le code PIN propriétaire partagé peut être configuré directement depuis /dashboard/agent-wallets sans liaison WhatsApp préalable (actif immédiatement à la première création, délai de 24h en cas de remplacement).
• Destinataires autorisés : Restriction facultative des virements aux seuls numéros de mobile sénégalais approuvés.
• Émission de clés d’agent (ak_live_... / ak_test_...) : La clé secrète de l’agent n’est affichée qu’une seule fois. L’approvisionnement ou la modification des plafonds (PATCH .../policy) requiert obligatoirement une session Propriétaire.

Paramètres du Compte et Administration

Accessible via /dashboard/settings, cet espace regroupe les contrôles administratifs réservés aux Propriétaires :

Onboarding KYC en direct (Live Onboarding)

Pour activer les encaissements réels en Mode En direct :

1. Profil de l’entreprise : Renseignez la raison sociale, le numéro NINEA et le registre RCCM.
2. Portefeuille de règlement : Indiquez le numéro de portefeuille Wave vérifié (+2217XXXXXXXX) destiné aux reversements automatiques.
3. Pièce justificative : Téléversez une pièce d’identité officielle du dirigeant ou le registre de commerce (PDF, JPEG ou PNG jusqu’à 5 Mo). Les données transitent directement en flux binaire sécurisé sans stockage en mémoire locale, et sont limitées à 10 tentatives par heure par adresse IP et par boutique (429 rate_limited avec Retry-After au-delà).
4. Suivi du dossier : Suivez l’évolution entre brouillon, soumis, approuvé ou rejeté. En cas de rejet, le motif du réviseur s’affiche pour permettre les corrections nécessaires.

Règlement automatique (Settlement)

• Reversement quotidien automatique des fonds disponibles vers votre portefeuille Wave validé.
• Horaire fixe : Exécution chaque jour à 18h00 heure de Dakar.
• Seuil minimal (min_amount) : Montant net minimal requis en XOF. Si le disponible est inférieur au seuil lors de l’exécution, les fonds sont reportés au lendemain.
• Historique et audit : Suivi de la date de dernière exécution (last_run) et de l’état du virement généré.

Applications connectées et Connecteurs IA (OAuth 2.1)

• Audit et contrôle des connecteurs tiers et agents IA (comme ChatGPT, Claude.ai ou connecteurs MCP) autorisés via https://mcp.xaalis.org.
• Affiche le nom de l’application cliente, la date d’autorisation et les portées accordées.
• Révocation immédiate : Vous pouvez révoquer un accès à tout instant depuis l’onglet dédié. La révocation invalide immédiatement les jetons d’accès actifs auprès de l’API.

Gestion de l’équipe

• Visualisez l’ensemble des collaborateurs et leurs rôles (Propriétaire, Développeur, Lecteur).
• Invitez de nouveaux membres par e-mail sécurisé (lien magique).
• Révoquez l’accès d’un collaborateur en un clic lors d’un départ.

Préférences de notifications (KYC-1)

• Accessible sous /dashboard/settings?tab=notifications (ou raccourci clavier 7), cet onglet réservé aux Propriétaires permet de configurer les canaux de notification (E-mail et WhatsApp) à l’échelle de l’organisation, partagés entre les modes Test et En direct (GET/PATCH /dashboard/v1/merchants/{merchantId}/{mode}/notification-preferences).
• Catégories :
  • kyc : Décisions d’approbation ou de rejet (incluant le motif de l’opérateur et les instructions de correction), rappels d’inactivité (J+2, J+7, J+14) et avis de suspension.
  • payments : Confirmations de paiements clients reçus.
  • payouts : Statuts des virements marchands sortants.
  • security : Alertes de sécurité obligatoires (changements de code PIN, déverrouillages, plafonds) — maintenues activées (true) sur tous les canaux.
• Suspension d’inactivité KYC et rétablissement : Un compte réel en attente dont le dossier KYC reste en brouillon ou rejeté reçoit des rappels aux jours 2, 7 et 14 puis est suspendu au jour 30. Même suspendu, le propriétaire conserve l’accès à /dashboard/settings?tab=onboarding et /dashboard/settings?tab=notifications pour corriger et resoumettre son dossier KYC, ce qui rétablit le compte au statut pending_review.

Inscriptions en libre-service (Sandbox et réel)

Pour prototyper vos intégrations, ou ouvrir votre boutique réelle, sans attendre d’intervention manuelle :

• Compte Sandbox instantané (/sandbox/signup, SB-OWNER) : génère immédiatement une boutique de test (mer_...), une clé d’API test (sk_test_...) et un secret de webhook (whsec_...) pour https://sandbox-api.xaalis.org, et rattache automatiquement l’adresse e-mail saisie comme Propriétaire (Owner) de cette nouvelle boutique de test. Vous pouvez vous connecter immédiatement au tableau de bord Sandbox (https://sandbox.xaalis.org/dashboard) par lien magique sans invitation opérateur.
• Compte réel en attente KYC (/live/signup) : crée votre boutique réelle au statut pending_review (sans clé réelle ni mouvement d’argent) et envoie un lien magique de connexion pour déposer votre dossier KYC dans le tableau de bord. L’identifiant sandbox_merchant_id éventuel est une simple référence : il ne relie pas les comptes et ne copie aucun réglage.
• Isolation de production et détection d’environnement (DX-1) : dès l’ouverture de session, GET /dashboard/v1/merchants expose test_mode_enabled: boolean (complété par un repli sur les erreurs 403 forbidden d’interdiction du mode test). Lorsque TEST_KEYS_ENABLED=false en production (pay.xaalis.org), toutes les pages du tableau de bord affichent un avertissement explicite en Mode Test permettant de basculer en Mode Live en un clic, d’ouvrir le tableau de bord Sandbox (https://sandbox.xaalis.org/dashboard, compte distinct) ou de créer un compte sur /sandbox/signup.