Paiements en masse (disbursement)

Epayment exécute des lots de paiements sortants (subventions, remboursements, indemnisations) pour une régie. Les lignes proviennent d'un upload fichier ou d'un fetch ERP.

Flux ERP fetch

Ce que l'ERP expose

GET /disbursements?batch_ref={ref}

Réponse : { "items": [ ... ] } conforme au contrat REST (objet ligne ci-dessous dans ce contrat).

Modes de paiement supportés en exécution v2 :

payment_method	payout requis
AIRTEL_MONEY	{ phone_e164, operator_hint? }
MTN_MOMO	{ phone_e164, operator_hint? }
BANK_TRANSFER	{ account_number, bank_code, account_holder_name, iban? }

MOBILE_MONEY legacy est normalisé via operator_hint. CASH et CHECK sont dépréciés et non exécutés en v2.

Alternative upload

L'officer peut importer un fichier CSV/Excel (template portail régie) au lieu du fetch ERP. Le pipeline validation → exécution est identique.

Sources batch : upload, erp_fetch, manual.

Machine à états du batch

États

État	Description
draft	Lot créé, lignes modifiables
importing	Import ERP ou parsing fichier en cours
pending_validation	En attente d'approbation officer
approved	Validé, prêt à exécuter
rejected	Refusé ; re-import ou re-soumission possible
executing	Versements PSP en cours
retrying	Nouvelle tentative sur lignes en échec
partially_failed	Terminé avec échecs partiels
completed	Toutes les lignes réussies
failed	Échec global
closed	Lot archivé

Actions officer par état

Action	États autorisés
import	draft, rejected
submit	draft, rejected
approve / reject	pending_validation
execute	approved
retry	partially_failed, failed, retrying
close	completed, partially_failed, failed
export_reconciliation	executing, retrying, completed, partially_failed, failed, closed

Exécution

• Une ligne à la fois via le connecteur de versement.
• Idempotence par line_ref et clé d'idempotence côté connecteur.
• Retry unitaire : échec ligne N ne rejoue pas les lignes 1…N-1 déjà réussies.
• États ligne : pending → executing → succeeded | failed.

Pas de webhook ministry

Ce flux est régie ↔ ERP ↔ PSP. Les webhooks application ministry ne s'appliquent pas. Notification ERP post-exécution : export rapport ou intégration métier hors contrat REST v1 standard.

Recette

• [ ] GET /disbursements?batch_ref= test retourne lignes valides
• [ ] payment_method et payout conformes (AIRTEL_MONEY / MTN_MOMO / BANK_TRANSFER)
• [ ] Preview lignes UI régie avant soumission
• [ ] Parcours complet draft → approved → completed sur sandbox
• [ ] Retry ligne en échec sans double paiement
• [ ] Export réconciliation cohérent avec registre ERP

Documentation associée

• Contrat REST
• Journal et recette
• Cas d'usage subventions