Guide de choix d'intégration

Matrice de décision pour sélectionner le canal d'intégration adapté au contexte métier et technique.

Arbre de décision

Profil	Canal	Auth	Endpoints clés	Notification métier
SI ministériel (redirect)	Ministry hosted	`sk_` application	`POST /checkout/sessions`, webhook HTTPS	`checkout.completed` (HMAC)
SI ministériel (iframe)	Ministry embed	`sk_` application	`POST /checkout/sessions`, `verify-completion`	Webhook + `verify-completion`
ERP régie (portail citoyen)	ERP REST	Credentials ERP (régie)	`GET /dues`, `POST /payment-confirmations`	Confirmation push Epayment → ERP
ERP régie (disbursement)	ERP REST	Credentials ERP (régie)	`GET /disbursements`	Statut batch côté régie
Portail eGouv multi-régies	eGouv + embed	`sk_` plateforme + `tenant_id`	`POST /checkout/sessions`, `verify-completion`	Webhooks régie cible + eGouv

Besoin	Hosted	Embed	ERP REST	eGouv
Paiement ponctuel dossier ministry	Recommandé	Optionnel	Non requis	Via `tenant_id`
Continuité UX sur portail ministry	Non	Recommandé	Non requis	Recommandé
Affichage créances contribuable	Non	Non	Requis	Requis (ERP régie)
Paiement panier multi-créances	Non	Non	Requis	Requis (ERP régie)
Paiements en masse (subventions)	Non	Non	Requis	Non
Multi-régies depuis un portail unique	Non	Possible	Non	Recommandé
Paiement agence (`payment_ref`)	Oui	Oui	Via portail citoyen	Oui

Critère	Hosted (`mode: hosted`)	Embed (`mode: embedded`)
Effort d'intégration frontend	Minimal (redirect HTTP)	SDK + origines autorisées
Expérience citoyen	Page checkout dédiée	Overlay sur le portail ministry
Confirmation synchrone	Webhook ou `GET ?order_id=`	`verify-completion` recommandé
Mobile web simple	Adapté	Adapté avec SDK
Branding ministry	Page Epayment	Iframe dans le portail

Les canaux sont complémentaires, pas exclusifs :

Contexte	Combinaison typique
Ministère sans portail citoyen Epayment	Ministry hosted ou embed seul
Régie avec portail citoyen	ERP REST + checkout hosted (via portail)
eGouv casier multi-tribunal	eGouv embed + ERP régie (webhooks régie `0001` + endpoints eGouv)
Régie avec subventions	ERP disbursement + ministry optionnel pour recettes ponctuelles

Un ministry peut intégrer le checkout API sans exposer d'ERP. Une régie peut connecter l'ERP pour le portail citoyen sans API ministry dédiée.

Situation	Recommandation
eGouv attend un webhook direct	Configurer les endpoints dans admin → Intégration eGouv (fan-out dual avec la régie). Préférer aussi `verify-completion` pour l'UX synchrone.
Clé plateforme sans `tenant_id`	Rejet `400 checkout.tenant_required`. Toujours fournir `tenant_id` (UUID ou slug régie).
Déblocage sur `success_url` seul	Insuffisant. Attendre webhook, `verify-completion` ou `GET ?order_id=` confirmé.
Retry après échec mobile money	Nouvelle session avec nouvelle `Idempotency-Key` ; `order_id` peut être réutilisé.
Direct push MM depuis le SI	Non supporté. Le SI ne poste pas de téléphone ni de collecte avec `sk_`. Hosted ou embed uniquement ; le rail (USSD, GIMAC, autre) reste abstrait côté Epayment.