Paiement en agence

Encaissement en espèces par un agent régie connecté, à partir de la référence payment_ref émise à la création de session.

Principe

Le SI ministry crée une session ; la réponse inclut payment_ref (16 chiffres). Le citoyen se présente en agence avec cette référence. L'agent régie saisit la référence dans le portail opérationnel ; la plateforme enregistre l'encaissement et clôt la session.

Aucun appel API ministry supplémentaire n'est requis pour le flux agence : le webhook checkout.completed notifie le SI comme pour le mobile money.

Format payment_ref

Propriété	Valeur
Longueur	16 chiffres
Structure	14 chiffres corps + 2 chiffres clé modulo 97
Corps	code_regie (3) + code_application (4) + numéro série (7)
Stabilité	Réutilisé pour le même order_id tant que la notice reste ouverte ou après échec (nouvelle session, même notice)

Validation côté plateforme : regex ^\d{16}$ et contrôle checksum.

Séquence

Côté agent régie (hors API ministry)

Opérations portail régie (/api/v1/regie/cash-collections) :

1. Lookup : GET …/cash-collections/lookup?payment_ref={16 chiffres} - affiche montant dû, statut session, order_id.
2. Collecte : POST …/cash-collections avec payment_ref, idempotency_key, montant encaissé.

Le SI ministry ne consomme pas ces endpoints. Ils sont documentés ici pour comprendre le délai entre remise espèces et webhook.

Webhook checkout.completed

Payload checkout.completed :

Champ	Valeur typique agence
event	checkout.completed
paid	true
order_id	Identifiant dossier ministry
notice_id	UUID notice
session_id	UUID session clôturée
metadata	Echo métadonnées session
service_code / service_label	Si service_code fourni à la création

Règle métier : sur paid: true et order_id connu, exécuter l'effet métier (déblocage dossier) de façon idempotente. Le canal d'encaissement n'apparaît pas dans le webhook ministry.

Cas limites

Situation	Comportement
Double collecte même payment_ref	Rejetée côté régie (notice déjà soldée)
Session open, citoyen paie en MM puis en agence	Première collecte réussie gagne ; seconde rejetée
Session expirée sans paiement	Nouvelle session ministry ; même payment_ref si notice réutilisée
Montant agence	Doit couvrir le montant dû (partiel selon configuration notice)

Complément checkout hébergé

Sur la page checkout, l'offre cash_agency affiche les instructions agence (référence, montant). Le citoyen peut choisir MM ou agence sur la même session open.

Vérification côté SI

Filet si webhook tardif :

GET /checkout/sessions?order_id={order_id}

Attendu après encaissement agence : status: completed, paid: true.