Guide administrateur

Ordre de mise en œuvre

Phase 1 — Mise en place de la filiale Orange

1. Configurer la filiale Orange Money (compte technique AskPayment, URLs test + production)
2. Tester l'authentification Orange (test 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

L'intégration repose sur le contrat d'interface Orange Money « AskPayment » V2 (Orange Finances Mobiles Mali). Toute la configuration est paramétrable : les valeurs par défaut vivent dans .env et une filiale ne renseigne que ce qui doit s'en écarter.

Pré-requis (à obtenir d'Orange Finances Mobiles Mali)

• Le compte technique loginOMY / passwordOMY, créé à la signature du contrat
• La durée de validité du token convenue (30 min, 24 H, 48 H…)
• Le tunnel IPsec monté entre notre passerelle et 197.155.141.49 : sans lui, aucun appel n'aboutit
• La déclaration chez Orange de notre URL de notification (/api/webhooks/orange/notification)

Étapes

1. Renseigner le compte technique dans .env.prod.local (jamais dans un fichier commité) : ORANGE_ASKPAY_PROD_LOGIN et ORANGE_ASKPAY_PROD_PASSWORD.
2. Aller dans Filiales / Pays, puis Configurer sur la filiale (Mali).
3. Section « Orange Money — AskPayment » : ne remplir que les champs qui doivent différer du paramètre global. Chaque champ affiche en dessous la valeur effectivement utilisée et son origine (global ou filiale).
4. Vérifier les IPs autorisées sur l'endpoint de notification.
5. Enregistrer (la filiale reste désactivée à ce stade).

Avant d'activer la filiale, validez que le compte technique fonctionne réellement (§2.1 du contrat : POST {BASE_URL}/login).

Étapes

1. Aller dans Filiales / Pays.
2. Sur la carte de la filiale, cliquer sur « Test » pour l'environnement de recette.
3. Le système appelle /login et attend un token dans l'en-tête Authorization. Le résultat s'affiche en haut de page :
   • ✅ Authentification OK + aperçu du token → la filiale répond
   • ❌ Échec + message → corriger le compte technique ou l'URL
4. Une fois le test OK, lancer « Prod » .
5. Pour un diagnostic détaillé (URLs résolues, origine de chaque paramètre, latence) : Tests → Authentification Orange.

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