Frais de service

Distinction entre montant dû (obligation ministry ou ligne ERP), frais de service (connecteur) et total payé par le citoyen.

Définitions

Terme	Champ API	Définition
Montant dû	amount (create ministry), amount_due_minor	Obligation métier : ce que le SI ministry ou l'ERP attend
Frais de service	service_fee_minor	Surcoût configuré par connecteur (MM, agence, carte, etc.)
Total citoyen	total_minor (ou amount_minor sur collecte)	Ce que le citoyen paie au PSP ou au guichet

Relation :

total_minor = amount_due_minor + service_fee_minor

Qui voit quoi

Acteur	Montant dû	Frais	Total
SI ministry (webhook, order_id)	Oui	Non	Non
Citoyen (checkout UI)	Oui	Oui	Oui
ERP (confirmation POST)	Oui (amount_minor encaissé dû)	Non	Non
Quittance Epayment	Oui	Oui	Oui

Le webhook checkout.completed ne contient pas les frais : corrélation sur montant dû et order_id.

Calcul des frais

Configuration par connecteur (momo, airtel, fake, cash_agency, paddle) :

{
  "percent_bps": 250,
  "fixed_minor": 100
}

Formule :

service_fee_minor = floor(amount_due_minor × percent_bps / 10000) + fixed_minor

Résolution : override tenant → plateforme → zéro si non configuré.

Exemple numérique

Étape	Montant (XAF, minor)
Ministry POST amount	5 000 (dû)
Frais 2,5 % + 100	225
Total citoyen MM	5 225
Webhook order_id / logique déblocage	5 000
Confirmation ERP amount_minor	5 000

Parcours

Parcours	Source du dû	Frais appliqués
Ministry hosted / embed	POST /checkout/sessions	À la sélection connecteur checkout
Portail citoyen	Ligne ERP amount_minor / partial	Idem sur session interne
Agence	Même règle	Instructions guichet sur total si frais actifs

Configuration

Frais configurés par opérateur (admin plateforme ou régie), pas via API ministry. Audit : connector.service_fee.update.

Règle fondamentale

La plateforme ne détient pas les fonds. Les frais font partie du flux citoyen vers PSP ou guichet ; le settlement PSP peut différer du montant dû ministry.

Références

• Checkout hébergé
• Index payloads