Guide administrateur

Ordre de mise en œuvre

Phase 1 — Mise en place de la filiale Orange

1. Configurer la filiale Orange Money (URL sandbox + production, Client ID/Secret, Merchant Key)
2. Tester la connexion OAuth (sandbox puis production)
3. Activer la filiale (visible des marchands)

Phase 2 — Onboarding marchand

4. Réceptionner et valider l'inscription self-service (statut PENDING_KYC)
5. Activer le compte marchand (clés nk_test_* opérationnelles)
6. Passer en production après validation KYC (génère les clés nk_live_*)

Phase 3 — Exploitation quotidienne

7. Superviser les transactions
8. Lancer la réconciliation J+1
9. Investiguer un webhook entrant
10. Consulter le journal d'audit
11. Régénérer les clés API d'un marchand
12. Gérer les rôles et utilisateurs internes

Avant que les marchands puissent encaisser, vous devez configurer les credentials OAuth fournis par Orange Money pour cette filiale.

Pré-requis (à demander à Orange)

• Client ID et Client Secret OAuth (obtenus sur developer.orange.com)
• Merchant Key spécifique à votre compte marchand Neka Paie côté Orange
• URL sandbox Orange (ex: https://api.sandbox.orange.com/orange-money-webpay/dev/v1)
• URL production Orange (ex: https://api.orange.com/orange-money-webpay/v1)

Étapes

1. Aller dans Filiales / Pays.
2. Cliquer sur l'icône de la filiale (ex: Mali) → page d'édition.
3. Section « Configuration Orange Money » :
   • URL Sandbox : pour les marchands en mode test
   • URL Production : pour les marchands actifs
   • Client ID et Client Secret OAuth
   • Merchant Key Orange
4. Cliquer sur « Enregistrer » (la filiale est sauvegardée mais reste désactivée).

Avant d'activer la filiale, validez que les credentials fonctionnent réellement avec Orange.

Étapes

1. Aller dans Filiales / Pays.
2. Sur la ligne de la filiale, cliquer sur « Test SB » pour tester l'environnement sandbox.
3. Le système tente d'obtenir un access_token via l'endpoint /token Orange.
4. Le résultat s'affiche en haut de page :
   • ✅ Connexion OK + aperçu du token → la filiale est prête
   • ❌ Échec + message d'erreur → corriger les credentials
5. Une fois sandbox OK, tester aussi « Test Prod » avant de basculer en production.

Statuts de test possibles

Après un test sandbox OK, activez la filiale pour la rendre visible des marchands.

Étapes

1. Sur la liste Filiales, cliquer sur « Activer » (vert).
2. Confirmer la popup.
3. La filiale apparaît immédiatement :
   • Dans la liste déroulante de création de marchand
   • Comme cible de routing pour les MSISDN du pays
   • Dans GET /api/v1/balances des marchands concernés

Les développeurs s'inscrivent en self-service via /developer/signup. Ils créent un compte en PENDING_KYC avec des clés nk_test_* immédiatement opérationnelles.

Étapes

1. Menu Marchands → filtrer par statut PENDING_KYC.
2. Ouvrir la fiche du nouveau marchand.
3. Vérifier :
   • Raison sociale et email cohérents
   • Cas d'usage déclaré (champ Notes)
   • Volume attendu
4. Demander les pièces KYC par email ou via votre canal habituel.
5. Annoter la fiche dans la zone Notes.

Une fois la KYC validée, activez le compte. Les clés nk_test_* deviennent opérationnelles côté API.

Statuts possibles

Étapes

1. Ouvrir la fiche du marchand → bouton vert « Activer ».
2. L'opération est journalisée (action MERCHANT_ACTIVATED).
3. Le développeur peut désormais appeler l'API en sandbox avec ses clés nk_test_*.

Lorsque le marchand a validé ses tests sandbox et son intégration, faites-le passer en production. De nouvelles clés nk_live_* sont émises et les anciennes nk_test_* sont invalidées.

Pré-requis

• Marchand en statut ACTIVE
• Mode sandbox actif (le bouton n'apparaît pas sinon)
• KYC complète et signée
• Filiale Orange testée en mode production (Test Prod OK)

Étapes

1. Ouvrir la fiche du marchand.
2. Cliquer sur le bouton orange « Passer en production » .
3. Confirmer la popup (les clés nk_test_* sont immédiatement invalidées).
4. 📋 Copier les nouvelles clés nk_live_* affichées sur la page suivante.
5. Transmettre les clés au développeur via un canal sécurisé.

FORMAT# Avant
API Key : nk_test_a1b2c3d4...

# Après
API Key : nk_live_x9y8z7w6...

Toutes les transactions de la plateforme sont consultables.

Filtres disponibles

• Texte libre : ID transaction, référence marchand, MSISDN, référence Orange.
• Statut : CREATED, INITIATED, PENDING, SUCCESS, FAILED, EXPIRED, REVERSED.
• Type : Cash-In, Cash-Out, Refund.
• Pays : filiale Orange.
• Date : du / au.

Étapes

1. Menu Transactions.
2. Appliquer les filtres souhaités.
3. Cliquer sur l'ID d'une transaction pour voir le détail :
   • Détails complets (montant, MSISDN masqué, marchand)
   • Réponse brute de l'opérateur Orange
   • Métadonnées envoyées par le marchand
   • Chronologie complète
   • Historique des webhooks envoyés au marchand

Job critique pour détecter les écarts entre Neka Paie et les relevés Orange.

Méthode 1 : interface web

1. Menu Réconciliation.
2. Choisir la date à réconcilier (par défaut J-1).
3. Optionnel : filtrer par filiale.
4. Cliquer sur « Lancer la réconciliation ».
5. Examiner le rapport :
   • Total transactions vs réussies / échouées / pending
   • Transactions matchées vs non matchées
   • Volume confirmé en devise locale
   • Taux d'écart (alerte si > 0,1 %)

Méthode 2 : ligne de commande (cron)

CRON# Tous les jours à 04h00 (J+1)
0 4 * * * cd /var/www/nekapay && php bin/console nekapay:reconcile

La commande affiche un tableau par filiale et déclenche un warning si le taux d'écart dépasse 0,1 %.

Quand un client conteste une transaction, vous pouvez retracer l'événement reçu.

Étapes

1. Menu Webhooks → onglet « Entrants Orange ».
2. Filtrer par provider_tx_id ou pays.
3. Cliquer sur l'œil pour voir le détail :
   • Payload brut JSON tel que reçu
   • Source IP (whitelist Orange)
   • Statut de signature (valide / invalide)
   • Statut de traitement (succès / doublon / erreur)

Cas typiques

Toutes les opérations sensibles sont enregistrées de manière append-only.

Actions tracées

• MERCHANT_CREATED — création d'un marchand
• MERCHANT_ACTIVATED / MERCHANT_SUSPENDED
• API_KEYS_REGENERATED — rotation de clés
• CASHIN_INITIATED / CASHOUT_INITIATED / REFUND_INITIATED
• STATUS_UPDATED — changement de statut transaction

Étapes

1. Menu Journal d'audit.
2. Filtrer par action, type d'entité, ID marchand.
3. Cliquer sur la loupe pour voir le diff JSON entre old_values et new_values.

À effectuer en cas de fuite suspectée ou de rotation périodique.

Étapes

1. Ouvrir la fiche du marchand.
2. Cliquer sur le bouton rouge « Régénérer clés ».
3. Récupérer immédiatement les nouvelles clés affichées.
4. Notifier le marchand pour qu'il bascule sa configuration.

Le préfixe est conservé : nk_test_* pour un marchand sandbox, nk_live_* pour un marchand production.

RBAC pour restreindre l'accès aux différentes sections.

Rôles techniques

• ROLE_NEKAPAY_ADMIN ou ROLE_ADMIN : accès complet au back-office
• ROLE_USER : accès à l'espace marchand uniquement

Étapes

1. Aller dans Utilisateurs ou Rôles.
2. Pour créer un admin : « Ajout utilisateur » → choisir le rôle approprié.
3. Permissions par module (Marchand, Transaction, etc.) configurables via Gérer les permissions.

Commande CLI

BASH"># Créer un admin
php bin/console nekapay:create-admin admin admin123