Casier judiciaire - hosted

Parcours MinJust : le citoyen quitte brièvement le portail pour payer sur la page checkout hébergée, puis revient via success_url ou notification webhook.

Acteurs

Acteur	Rôle
Citoyen	Soumet la demande et paie (mobile money ou agence)
SI MinJust (backend)	Crée la session, redirige, traite le webhook
Epayment API	Orchestre la session et constate le paiement
Checkout hébergé	Interface citoyen (canaux MM et agence)
Endpoint webhook MinJust	Réception HMAC des événements checkout

Prérequis

• Application ministry configurée (clé sk_test_ ou sk_live_, catalogue casier_judiciaire).
• Endpoint webhook HTTPS abonné à checkout.completed (et aux terminaux si logique métier requise).
• webhook_secret stocké en coffre ; vérification HMAC implémentée.
• Montant dû calculé côté MinJust ; order_id stable par dossier.
• success_url configurée (ne suffit pas seule pour débloquer le dossier).

Séquence

Étapes métier

1. Citoyen soumet la demande sur le portail MinJust.
2. Backend MinJust : POST /checkout/sessions avec order_id, amount, service_code: casier_judiciaire, metadata, success_url.
3. Redirect du citoyen vers checkout_url.
4. Citoyen paie en mobile money ou note payment_ref pour paiement en agence.
5. Epayment envoie checkout.completed au webhook MinJust.
6. MinJust débloque le dossier (idempotent sur order_id).

Exemple création

curl -X POST "https://paymentdev-api.akieni.tech/api/v1/checkout/sessions" \
  -H "Authorization: Bearer sk_test_XXXX" \
  -H "Idempotency-Key: CJ-2026-88421" \
  -H "Content-Type: application/json" \
  -d '{
    "order_id": "CJ-2026-88421",
    "amount": 5000,
    "description": "Casier judiciaire",
    "service_code": "casier_judiciaire",
    "metadata": { "tribunal": "Brazzaville" },
    "success_url": "https://casiers.minjust.gouv/retour/succes"
  }'

Chemins d'échec

Scénario	Signal	Action MinJust
Session TTL sans paiement	Webhook checkout.expired ou GET status: expired	Garder dossier bloqué ; proposer nouvelle session (nouvelle Idempotency-Key)
Collect MM refusé ou timeout	Webhook checkout.failed, failure_code (collect.rejected, collect.approval_timeout)	Ne pas débloquer ; même order_id possible avec nouvelle session
Citoyen annule sur checkout	Webhook checkout.cancelled	Dossier reste en attente de paiement ; nouvelle session si le citoyen revient

Critères d'acceptation

• [ ] POST /checkout/sessions retourne checkout_url et session_id cohérents.
• [ ] Paiement sandbox (MM ou agence) aboutit à webhook checkout.completed signé et validé.
• [ ] unlockDossier exécuté une seule fois même si webhook rejoué (x-epayment-event-id ou (session_id, event)).
• [ ] Retour success_url seul ne débloque pas le dossier sans webhook ou GET confirmé.
• [ ] Montant webhook et order_id reflètent le montant dû ministry, pas le total citoyen incluant frais (frais de service).
• [ ] Échec MM : nouvelle session créée sans double encaissement sur le même dossier payé.

Références

• Checkout hébergé
• Webhooks
• Recette ministry