Modules — Finance¶
Ces modules portent l'argent : encaissement, répartition des commissions, escrow, soldes et retraits. Toute l'arithmétique passe par une représentation exacte (voir l'ADR sur la représentation monétaire).
| Module | app/ · domain/ · web/ |
Rôle |
|---|---|---|
| payments | payments/ |
Encaissement, liens de paiement, échéances, statut, escrow, commissions, intégration passerelle. |
| money | money/ (domain/) |
Valeur monétaire atomique, calculs de commission. |
| transactions | transactions/ (domain/) |
Grand livre en partie double de tous les mouvements d'argent. |
| wallets | wallets/ |
Portefeuilles utilisateurs (solde), relevés. |
| withdrawals | withdrawals/ |
Demandes de retrait, flux d'approbation, statut, historique. |
| kyc | kyc/ |
KYC (Know Your Customer) : soumission, documents, revue/approbation. |
payments¶
Encaisse par Mobile Money ou carte via la passerelle (Moneroo) encapsulée dans adapters/payments/. Gère les liens de paiement, les échéances, le suivi de statut, l'escrow et la répartition des commissions. Les mises à jour de statut arrivent par webhook signé (voir Transverses › webhooks et le runbook de smoke-test Moneroo).
Indisponibilité passerelle
Si la passerelle est injoignable, le service lève PaymentGatewayError → 503. Le client propose de réessayer plus tard sans considérer le paiement comme définitivement échoué. Une signature de webhook invalide renvoie 401 avec { "message": "invalid_signature" }.
money¶
Objet-valeur monétaire atomique et calculs de commission. La représentation interne est en arithmétique exacte (Decimal), stockée en DECIMAL(20,4) et sérialisée en nombre JSON à la frontière HTTP. Détails et justification : ADR — Représentation monétaire.
transactions¶
Grand livre en partie double de tous les mouvements (paiements, commissions, retraits, remboursements). Son invariant est protégé par LedgerError, volontairement non filtrée (résout en 500, reste visible pour Sentry) — voir Erreurs & i18n. Ne jamais reclasser une LedgerError en erreur de validation.
wallets¶
Portefeuilles utilisateurs : solde courant et relevés. Alimentés par les écritures du grand livre (commissions encaissées, retraits).
withdrawals¶
Demandes de retrait depuis un portefeuille : création, flux d'approbation, suivi de statut et historique. Une ligne verrouillée ou un état incompatible est rejeté par une erreur de conflit (409).
Pas de garde-fou UX côté backend
Le backend n'impose que les vérifications de correction (auth, lignes verrouillées, état archivé). Les confirmations type « êtes-vous sûr ? » sont une préoccupation frontend — on ne câble jamais de confirm: true dans les endpoints.
kyc¶
Collecte et revue KYC requise pour les fonctionnalités financières : soumission, upload de documents (via storage), puis approbation/refus. Conditionne l'accès aux retraits et à certains encaissements.