Service Providers Gateway

Passerelle d'intégration vers les opérateurs externes (Mobile Money, banques partenaires). Normalise les contrats hétérogènes (REST, USSD, batch, webhooks) vers une interface stable utilisable par l'orchestrator.

État : service en démarrage (v0.0.1). Squelette posé, Swagger configuré, base de données prête, mais peu d'implémentation visible côté contrôleurs et adapters. Cette page documente l'intention et le scope V1 prévu.

Identité

Attribut	Valeur
Package	@nex/service-providers-gateway v0.0.1
Port	3000
Schéma DB	providers_gateway (PostgreSQL, défini dans src/data-source.ts)
Swagger	services/providers-gateway/src/main.ts:41 — actif, tags providers, provider-transactions, callbacks
README	❌ absent
Owner	@platform-team

Surface API actuelle

Controller	Route	Endpoints
app.controller.ts	/	2 (root + health)

Aucun controller métier visible à ce stade. À enrichir lors de l'implémentation.

Responsabilité attendue

• Adaptateur unique vers les providers externes. Un service métier (orchestrator, mass-payments) appelle une interface normalisée ; le gateway parle au provider dans son protocole.
• Gestion des webhooks entrants : signature, idempotency, ack vers le provider, fan-out vers les services consommateurs.
• Gestion des tokens d'authentification providers (renouvellement, rotation, scope).
• Audit des appels sortants et entrants pour reconstitution forensic.

Providers prévus

À confirmer selon le scope commercial V1 :

• Opérateurs Mobile Money de la zone CEMAC (Orange Money, MTN MoMo, Moov Money, Airtel Money — selon couverture).
• Banques partenaires (intégrations comptes de cantonnement).
• Émetteurs / acquéreurs carte (si scope card actif).

Pattern d'adaptateur attendu

Convention de structure de dossiers recommandée pour chaque nouveau provider :

src/providers/<provider-name>/
  ├── <provider>.adapter.ts        # implémente ProviderAdapter
  ├── <provider>.client.ts         # client HTTP / USSD spécifique
  ├── dto/                         # DTOs in/out spécifiques au provider
  ├── mappers/                     # field-mapping vers contrat interne Nex
  └── webhooks/                    # handlers callbacks entrants

Le contrat normalisé est porté par service-catalog (FieldMapping, EndpointResponseMapping) — voir /services/service-catalog/.

Vendor risk

Chaque provider doit faire l'objet d'une fiche vendor risk dans /compliance/third-party-vendors (Lot 6) :

• Couverture géographique et SLA contractuel.
• Sécurité (TLS, signature webhook, IP whitelist).
• Politique de rotation des credentials.
• Plan de bascule en cas d'indisponibilité.

Dépendances actuelles

• Externes : @nestjs/platform-express, typeorm, pg, swagger-ui-express.
• Intra-monorepo : aucune détectée à ce stade.

Pages à produire quand l'implémentation arrive

• api.md — endpoints exposés (initier paiement, recevoir callback)
• data-model.md — tables providers, transactions providers, callbacks
• runbook.md — provider down, idempotency callback, rollback paiement
• threat-model.md — signature webhooks, IP allowlist, replay
• providers/<name>.md — un fichier par provider intégré