eGouv / e-Citizen

Intégration via clé API plateforme pour un portail transverse qui cible plusieurs régies et ministères. Le cas d'usage principal est le checkout embarqué.

Clé plateforme

Aspect	Règle
Auth	Authorization: Bearer sk_... (scope platform)
tenant_id	Obligatoire sur chaque POST /checkout/sessions (UUID ou slug régie)
Sans tenant_id	400 checkout.tenant_required

Checkout embed (cas principal)

await epayment.post('/checkout/sessions', {
  mode: 'embedded',
  tenant_id: 'minjust',
  service_code: 'casier_judiciaire',
  order_id,
  amount,
});

Le back eGouv transmet client_secret au front ; le SDK ouvre l'overlay. Confirmation : verify-completion.

Origines embed

Configuration globale : admin super-admin → Intégration eGouv.

Exemples : https://egov.gouv.cg, https://ecitizen.gouv.cg

Ces origines ne se configurent pas sur une application ministry isolée (liste d'origines de l'application).

Webhooks : double livraison

Les webhooks checkout (checkout.completed, checkout.expired, …) initiés avec une clé plateforme sont livrés en fan-out dual :

1. Endpoints de l'application intégrateur de la régie ciblée (souvent code 0001)
2. Endpoints eGouv configurés dans admin → Intégration eGouv (application plateforme 0000)

Les endpoints eGouv sont indépendants des clés API : un seul jeu d'URL reçoit les événements pour toute clé plateforme.

Une session créée avec une clé application (ministry) ne livre que vers les endpoints de cette application, pas vers eGouv.

Options eGouv pour la confirmation métier

Option	Mécanisme	Usage
1 - Recommandé UX	verify-completion après embed	Déblocage synchrone dossier eGouv
2 - Webhook eGouv	Endpoints configurés dans Intégration eGouv	File durable côté portail
3 - Bus interne	Ministry consomme webhook régie et notifie eGouv	Couplage SI ministry ↔ eGouv
4 - Fallback	GET /checkout/sessions?order_id= + sk_ plateforme + tenant_id	Webhook retardé ou perdu

verify-completion plateforme

Auth sk_ plateforme acceptée. La réponse inclut tenant_id ; le back eGouv vérifie que order_id correspond au dossier du tenant attendu.

Corps optionnel pour double contrôle :

{
  "completion_token": "cpt_...",
  "tenant_id": "minjust"
}

SDK

Canal recommandé : CDN /sdk/v1.js (pas de dépendance npm requise sur portail legacy). Détail : Référence SDK.

Hosted redirect

Possible avec mode: hosted + tenant_id si la redirection full-page est acceptable. L'embed reste préféré pour l'UX unifiée eGouv.

Recette

Checklist complète : Checklist eGouv.

Documentation associée

• Checkout embarqué
• Casier embed