Appearance
Paiement par carte
Encaissement par carte bancaire (acquéreur connecté) depuis le checkout hébergé ou embed. Le SI ministry ne collecte aucune donnée carte (PAN, CVV, date d'expiration), ne choisit pas le canal de paiement et n'appelle pas les routes de collecte du checkout citoyen.
Audience
| Acteur | Autorisé | Interdit |
|---|---|---|
Backend SI (sk_ ministry / eGouv) | POST /checkout/sessions (devise carte), webhooks, verify-completion | Collecte carte, routes checkout offers / collecte |
| Checkout Epayment (hosted / SDK) | Redirection ou overlay vers l'acquéreur PCI | Clé sk_ |
La redirection acquéreur est orchestrée par le checkout Epayment, pas par le backend ministry. Même rationale que le mobile money : abstraire le rail de paiement pour permettre un swap de prestataire sans nouveau contrat SI.
Contexte
Le paiement par carte complète mobile money (XAF) et agence. Il est disponible lorsque la session est créée dans une devise supportée carte (voir Référence API). L'offre carte apparaît alors au checkout citoyen ; le canal technique est CARD.
Le citoyen saisit sa carte sur la page de l'acquéreur (hébergée PCI). Epayment orchestre la transaction et constate le paiement ; le webhook ministry reste identique aux autres canaux.
Prérequis
| Élément | Détail |
|---|---|
| Devise session | Code ISO 4217 de la liste carte (ex. EUR, USD) ou XAF pour MM/agence uniquement |
| Montant | Unités mineures ISO 4217 uniquement. 10000 + EUR = 100,00 EUR. 100 + EUR = 1,00 EUR. XAF : 5000 = 5 000 FCFA (inchangé). Détail : Référence API. |
| Connecteur carte | Activé pour la régie et l'environnement (sandbox ou live) |
| Webhook ministry | Endpoint HTTPS abonné à checkout.completed |
| Embed (optionnel) | Origines autorisées configurées ; SDK /sdk/v1.js |
Le SI ministry envoie uniquement order_id, amount, currency et métadonnées. Aucun champ téléphone ni carte.
Flux
Hosted vs overlay
| Mode session | UX carte | Recommandation |
|---|---|---|
hosted | Page checkout Epayment puis redirection vers l'acquéreur | Parcours simple, redirect full-page |
embedded | Overlay SDK ; iframe checkout ouvre l'acquéreur dans le flux embed | Préféré pour garder le citoyen sur le portail ministry |
En embed, le SDK émet epayment.checkout.pending pendant le paiement carte externe. La fermeture de l'overlay demande confirmation tant que le collect est en cours.
Course webhook acquéreur
Les notifications entrantes acquéreur ne portent pas directement le statut final : Epayment extrait une référence de corrélation puis interroge l'acquéreur (inquire) avant d'appliquer un statut. Ne pas implémenter de logique parallèle côté SI sur des callbacks PSP bruts.
Comportement checkout (observabilité SI)
Sur le checkout citoyen, l'offre carte n'apparaît que si la devise de session est supportée. Sur session XAF, seuls mobile money et agence sont proposés.
Le SI n'a pas à parser de next_action ni de jeton acquéreur. Diagnostic support éventuel : logs checkout / journal plateforme, pas un contrat ministry.
Délai d'approbation carte
| Aspect | Valeur |
|---|---|
| Délai d'approbation (défaut) | 1 800 s (30 min) |
| Refus / timeout carte | Session reste open (retry citoyen) |
PCI et données carte
Epayment et le checkout citoyen ne demandent jamais de PAN, CVV ou date d'expiration au SI ministry ni au portail intégrateur. La saisie carte a lieu uniquement sur la page acquéreur certifiée PCI.
Erreurs
Refus et timeout (session reste ouverte)
Contrairement au mobile money, un refus carte ou un timeout d'approbation carte ne clôt pas la session checkout :
| Situation | Session | Webhook checkout.failed | Action citoyen |
|---|---|---|---|
| Refus acquéreur | Reste open | Non (collect échoué, retry possible) | Choisir une autre offre ou relancer carte |
| Timeout approbation carte | Reste open | Non | Message FR puis nouvelle tentative |
| Abandon citoyen (navigation) | Reste open | Non | Reprendre sur la même session |
Message citoyen timeout : « Délai de paiement par carte dépassé. Aucun montant débité. Vous pouvez réessayer. »
Pour clôturer sans payer : expiration TTL session (24 h) ou POST /checkout/sessions/{id}/cancel.
Comparaison mobile money
| Mobile money | Carte | |
|---|---|---|
| Refus / timeout | Session failed, webhook checkout.failed | Session open, retry sur place |
| Délai approbation | 90 s | 1 800 s |
| Champ citoyen | Numéro MM sur le checkout | Aucun côté SI |
Détail MM : Mobile money.
Devise non supportée
Création session avec devise hors liste : HTTP 422, code generic.validation_failed, message « The currency is not supported. »
Connecteur indisponible
Sur le checkout, message citoyen si aucun connecteur carte actif pour la régie et la devise. Le SI ne pilote pas ce cas via une route de collecte.
Recette
Checklist
- [ ] Session
currency: EUR(ou autre devise carte) : offre carte visible sur le checkout - [ ] Session
currency: XAF: offre carte absente ; MM et agence présents - [ ] Devise invalide (ex.
XXX) :422 generic.validation_failed - [ ] Paiement sandbox carte (via hosted ou embed) : webhook
checkout.completed,paid: true - [ ] Refus sandbox : session toujours
open, pas decheckout.failed - [ ] Timeout carte simulé : session
open, message FR timeout - [ ] Embed : overlay reste
pendingpendant redirect acquéreur ; verify-completion après succès - [ ] Aucune donnée PAN dans les logs SI ni requêtes ministry
- [ ] Confirmation ERP portail citoyen (si applicable) :
payment.channel = CARD(voir Contrat REST)
Confirmation ministry
Chemin principal : webhook checkout.completed (paid: true), sans canal PSP dans le payload.
Mode embed : compléter par POST /checkout/sessions/verify-completion. Voir Checkout embarqué.