Workflow de Décaissement de Prêt

Vue d’ensemble

Le Workflow de Décaissement de Prêt dans Agatabo décrit le processus de création des prêts, de validation appropriée et d’enregistrement du décaissement avec une comptabilité exacte.

Implémentation actuelle : la création et le décaissement du prêt se font simultanément dans un seul appel API. Le prêt est créé avec le statut ACTIVE et décaissé immédiatement.Le statut PENDING existe dans le schéma de base de données, mais il n’est pas actuellement utilisé par l’API. Un workflow d’approbation en plusieurs étapes pourra être ajouté dans de futures versions.

Vue d’ensemble du workflow

Préparation → Création et validation → Décaissement automatique → Suivi

Étape 1 : Préparation avant le prêt

Qui : Agent de crédit ou Administrateur Avant de créer le prêt dans le système :

Vérifier l'éligibilité du membre

Le Membre a le solde d’Épargne requis (généralement 20 à 30 % du montant du prêt)
Le Membre n’a aucun prêt existant ACTIVE ou DEFAULTED
Le Membre a le rôle “member” assigné (requis pour l’éligibilité au prêt)
Le Membre est actif dans l’organisation

Évaluer la capacité de remboursement

Examiner les sources de revenu du Membre
Vérifier l’historique de prêt du Membre (défauts passés ?)
Vérifier que le Membre peut payer les échéances
Évaluer la solvabilité générale

Collecter les garanties

Garants : autres membres actifs qui cosignent
Nantissements : actifs physiques (propriété, équipement) avec valeurs estimées
Exigence d’Épargne : solde d’Épargne minimum que le Membre doit maintenir
Documents : photos, titres, évaluations, accords

Calculer les conditions du prêt

Déterminer le montant du Capital (dans les limites de l’organisation)
Décider la Période du prêt (mois)
Définir le taux d’Intérêt (selon la politique de l’organisation)
Choisir la méthode de calcul de l’Intérêt
Calculer les échéances estimées

Checklist avant la saisie dans le système :

✅ Membre éligible au prêt
✅ Garanties suffisantes pour couvrir le montant du prêt
✅ Conditions du prêt conformes aux politiques de l’organisation
✅ Documentation requise collectée
✅ Approbation du comité de prêt obtenue (si requise par l’organisation)

Étape 2 : Création et Décaissement du Prêt

Qui : Utilisateur avec la permission loans:write Endpoint API : POST /loans

Requête

POST /loans
Headers:
  x-organization-id: {organizationId}
  x-idempotency-key: {unique-key}
Body:
{
  "organizationUserId": "orguser-123",
  "principalAmount": 500000,
  "period": 12,
  "interestRate": 10,
  "interestRateType": "YEARLY",
  "interestCalculationType": "REDUCING_BALANCE",
  "interestPaymentTiming": "WITH_INSTALLMENTS",
  "installmentType": "EQUAL_TOTAL",
  "paymentAllocationOrder": "INTEREST_FIRST",
  "startDate": "2026-06-01",
  "purpose": "Business expansion",
  "bankAccountId": "bank-456",
  "loanSecurities": [
    {
      "type": "GUARANTOR",
      "organizationUserId": "orguser-789",
      "description": "John Doe - Co-signer"
    },
    {
      "type": "COLLATERAL",
      "value": 600000,
      "description": "Motorcycle - 2020 model"
    }
  ],
  "disbursementFeePercentage": 1.0,
  "disbursementFeeType": "PERCENTAGE"
}

Champs requis :

Champ	Type	Description
`organizationUserId`	string	Emprunteur (doit avoir le rôle “member”, être actif, et n’avoir aucun prêt existant `ACTIVE`/`DEFAULTED`)
`principalAmount`	number	Montant du prêt
`period`	number	Durée du prêt en mois
`interestRate`	number	Pourcentage du taux d’Intérêt
`interestRateType`	enum	”MONTHLY” ou “YEARLY”
`interestCalculationType`	enum	”SIMPLE”, “COMPOUND” ou “REDUCING_BALANCE”
`startDate`	string	Date de début du prêt (format ISO)
`bankAccountId`	string	Compte Bancaire pour le Décaissement

Champs optionnels :

Champ	Type	Défaut	Description
`interestPaymentTiming`	enum	Depuis les paramètres de l’organisation	”IN_ADVANCE” ou “WITH_INSTALLMENTS”
`installmentType`	enum	Depuis les paramètres de l’organisation	”EQUAL_PRINCIPAL” ou “EQUAL_TOTAL”
`paymentAllocationOrder`	enum	Depuis les paramètres de l’organisation	”INTEREST_FIRST”, “PRINCIPAL_FIRST” ou “PROPORTIONAL”
`purpose`	string	null	Description de l’objet du prêt
`loanSecurities`	array	[]	Garants, Nantissements, exigences d’Épargne
`disbursementFeeType`	enum	Depuis les paramètres de l’organisation	”PERCENTAGE” ou “FIXED_AMOUNT”
`disbursementFeePercentage`	number	Depuis les paramètres de l’organisation	Pourcentage des frais (par ex. 1.0 = 1 %)
`disbursementFeeFixedAmount`	number	Depuis les paramètres de l’organisation	Montant fixe des frais
`bankChargeAmount`	number	null	Frais de virement bancaire
`skipNegativeBalanceCheck`	boolean	false	Autoriser les soldes négatifs (à utiliser avec prudence)

Ce qui se passe automatiquement

Lorsque le prêt est créé, le système effectue ces actions atomiquement dans une seule transaction de base de données :

Valider l'éligibilité du membre

Le Membre existe dans l’organisation
Le Membre est actif
Le Membre a le rôle “member” assigné
Le Membre n’a aucun prêt existant ACTIVE ou DEFAULTED

Erreur si : le Membre est inéligible ou a déjà un prêt actif

Valider les politiques de l'organisation

Le montant du Capital est dans les limites configurées
La Période est dans le maximum autorisé (si configuré)
Capital ≤ (Épargne du membre × max_loan_percentage)
L’échelle du montant correspond aux paramètres de devise de l’organisation

Erreur si : les politiques de prêt de l’organisation sont violées

Valider les garanties

Valeur totale des garanties ≥ montant du prêt
Les Garants sont des membres actifs
L’exigence d’Épargne ne dépasse pas l’Épargne disponible du Membre
Toutes les valeurs de garantie utilisent la bonne précision décimale

Erreur si : garanties insuffisantes

Calculer les échéances

Calcule l’EMI (échéance mensuelle équivalente)
Génère l’échéancier
Calcule l’Intérêt total
Applique les règles d’arrondi configurées

Échéances créées avec des dates d’échéance basées sur la Période

Créer l'enregistrement du prêt

Statut défini sur ACTIVE (pas PENDING)
Numéro de compte unique assigné au prêt
Échéancier verrouillé
Garanties stockées en JSON

Résultat : prêt immédiatement actif et décaissé

Créer les comptes du Grand Livre

Compte LOAN_RECEIVABLE (suivi du Capital)
Compte INTEREST_RECEIVABLE (suivi de l’Intérêt)
Compte PENALTY_RECEIVABLE (suivi des Pénalités)

Résultat : comptes du Grand Livre dédiés à ce prêt

Comptabiliser l'Écriture Comptable de décaissement

Écriture de base (Intérêt avec échéances, frais depuis la caisse) :

Dr LOAN_RECEIVABLE           500,000
Dr INTEREST_RECEIVABLE       total_interest
Cr CASH (bank account)       500,000 - fee
Cr INTEREST_INCOME           total_interest
Cr DISBURSEMENT_FEE_INCOME   fee_amount

Variantes :

Si les frais sont déduits de l’Épargne : écriture DISBURSEMENT_FEE_PAYMENT séparée
Si l’Intérêt est payé d’avance depuis l’Épargne : écriture INTEREST_PAID_IN_ADVANCE séparée
Si l’Intérêt est payé d’avance depuis la caisse : INTEREST_RECEIVABLE n’est pas débité, CASH est réduit de l’Intérêt
Si frais bancaires : écriture BANK_CHARGE supplémentaire

Résultat : prêt décaissé, comptes mis à jour

Envoyer la notification

Si l’organisation a activé l’e-mail/SMS :

E-mail envoyé à l’emprunteur avec les détails du prêt
SMS envoyé avec le message d’approbation du prêt
Le message inclut le montant de l’échéance et l’échéancier

Exemple de message : “Votre prêt de 500 000 RWF a été approuvé ! 12 échéances mensuelles de 45 000 RWF chacune.”

Réponse

Succès (201 Created) :

{
  "message": "Loan created successfully",
  "data": {
    "id": "loan-123",
    "accountNumber": "L-00042",
    "organizationUserId": "orguser-123",
    "principalAmount": 500000,
    "period": 12,
    "interestRate": 10,
    "interestRateType": "YEARLY",
    "status": "ACTIVE",
    "startDate": "2026-06-01T00:00:00.000Z",
    "disbursementFee": 5000,
    "loanReceivableLedgerAccountId": "acc-456",
    "interestReceivableLedgerAccountId": "acc-457",
    "penaltyReceivableLedgerAccountId": "acc-458",
    "createdAt": "2026-06-13T10:30:00.000Z"
  }
}

Erreurs

Statut	Erreur	Cause
400	”x-idempotency-key header is required”	Clé d’idempotence manquante
404	”Organization user not found, inactive, or does not belong to this organization”	`organizationUserId` invalide ou Membre non actif
409	”Organization user already has an active or defaulted loan”	Le Membre a déjà un prêt `ACTIVE` ou `DEFAULTED`
400	”Loan period cannot exceed X month(s)“	La Période dépasse le paramètre `max_period` de l’organisation
400	”Principal exceeds max allowed from max loan percentage rule”	Capital > (Épargne × `max_loan_percentage`)
400	”Insufficient security coverage”	Total des garanties < montant du prêt
400	Erreurs de validation diverses	Données invalides, problèmes de précision décimale, etc.

Étape 3 : Après le Décaissement

Qui : Agent de crédit, Trésorier

Actions immédiates

Décaisser les fonds au membre

Méthode 1 : déduction depuis l’Épargne (si frais/Intérêt déduits de l’Épargne) :

Le système a déjà déduit le montant du compte d’Épargne du Membre
Le Membre reçoit en espèces : Capital - (frais si depuis la caisse) - (Intérêt si depuis la caisse et payé d’avance)
Compter l’argent en présence du Membre
Le Membre signe le reçu

Méthode 2 : virement bancaire :

Virer depuis le Compte Bancaire de l’organisation vers le compte du Membre
Enregistrer le numéro de référence bancaire
Montant : Capital - (frais/Intérêt déduits de la caisse)

Méthode 3 : espèces depuis le bureau :

Retirer depuis la banque de l’organisation
Remettre l’argent au Membre
Le Membre signe le reçu

Classer la documentation du prêt

Contrat de prêt signé
Documents de Nantissement (titres, évaluations, photos)
Accords de Garant
Reçu de Décaissement
Documents de Garantie

Fournir l'échéancier au membre

Exporter l’échéancier depuis le système
L’imprimer et le remettre au Membre
Expliquer les méthodes de paiement
Confirmer que les dates d’échéance sont comprises
Fournir les coordonnées du trésorier

Configurer les rappels de paiement

Ajouter le prêt à la liste de suivi
Configurer des rappels automatiques de paiement (3 à 5 jours avant l’échéance)
Noter la date de la première échéance
Configurer les règles de Pénalité si applicable

Suivi continu

Suivre les paiements

Surveiller les dates d’échéance
Envoyer des rappels avant les échéances
Enregistrer rapidement les paiements avec POST /loans/{loanId}/repay
Mettre à jour le statut de paiement (à temps, en retard, manqué)

Gérer les retards

Identifier immédiatement les paiements en retard
Relancer le Membre (appel téléphonique, visite)
Appliquer les Pénalités selon la politique de l’organisation
Escalader au comité de prêt si nécessaire
Envisager une restructuration pour les cas difficiles

Surveiller la santé du prêt

Examiner régulièrement les arriérés (rapport Prêts en Cours)
Suivre les jours de retard
Classer les prêts (courant, 1-30 jours, 31-90 jours, 90+ jours)
Mettre le statut à DEFAULTED si nécessaire

Options de frais de Décaissement et de paiement de l’Intérêt

Options de déduction des frais

Option 1 : frais déduits de la caisse (par défaut) :

Dr LOAN_RECEIVABLE           500,000
Cr CASH                      495,000  (500,000 - 5,000 fee)
Cr DISBURSEMENT_FEE_INCOME     5,000

Le Membre reçoit : 495 000 RWF Option 2 : frais déduits de l’Épargne (si disbursementFeeFromSavings: true) :

Main entry:
Dr LOAN_RECEIVABLE           500,000
Cr CASH                      500,000

Separate fee entry:
Dr SAVINGS (member)            5,000
Cr DISBURSEMENT_FEE_INCOME     5,000

Le Membre reçoit : 500 000 RWF en espèces, mais 5 000 sont déduits de l’Épargne

Options de calendrier de paiement de l’Intérêt

Option 1 : Intérêt payé avec les échéances (par défaut) :

Dr LOAN_RECEIVABLE            500,000
Dr INTEREST_RECEIVABLE         60,000
Cr CASH                       500,000
Cr INTEREST_INCOME             60,000

Le Membre paie l’Intérêt progressivement avec chaque échéance. Option 2 : Intérêt payé d’avance depuis la caisse (si interestPaymentTiming: "IN_ADVANCE") :

Dr LOAN_RECEIVABLE            500,000
Cr CASH                       440,000  (500,000 - 60,000 interest)
Cr INTEREST_INCOME             60,000

Le Membre reçoit : 440 000 RWF (Intérêt déduit à l’avance) Option 3 : Intérêt payé d’avance depuis l’Épargne (si interestPaymentTiming: "IN_ADVANCE" et advanceInterestFromSavings: true) :

Main entry:
Dr LOAN_RECEIVABLE            500,000
Cr CASH                       500,000

Advance interest entry:
Dr SAVINGS (member)            60,000
Cr INTEREST_RECEIVABLE         60,000

Le Membre reçoit : 500 000 RWF en espèces, mais 60 000 sont déduits de l’Épargne

Configuration depuis les paramètres de l’organisation

Plusieurs paramètres de prêt utilisent par défaut les paramètres globaux de l’organisation (champ loanSettings) :

Paramètre	Défaut	Description
`interest_payment_timing`	”WITH_INSTALLMENTS”	Moment où l’Intérêt est payé
`installment_type`	”EQUAL_PRINCIPAL”	Méthode de calcul des échéances
`payment_allocation_order`	”INTEREST_FIRST”	Méthode d’allocation des paiements
`max_loan_percentage`	(aucun)	Prêt maximum comme multiple de l’Épargne (par ex. 3.0 = 3× l’Épargne)
`max_period`	(aucun)	Durée maximale du prêt en mois
`disbursement_fee_percentage`	0	Pourcentage de frais par défaut
`disbursement_fee_type`	”PERCENTAGE"	"PERCENTAGE” ou “FIXED_AMOUNT”
`disbursement_fee_fixed_amount`	0	Montant fixe des frais
`deduct_disbursement_fee_from_savings`	false	Déduire les frais de l’Épargne au lieu de la caisse
`deduct_advance_interest_from_savings`	false	Déduire l’Intérêt payé d’avance de l’Épargne au lieu de la caisse

Ces paramètres s’appliquent automatiquement sauf s’ils sont remplacés dans la requête de création du prêt.

Checklist complète du workflow

Avant la création

✅ Éligibilité du Membre vérifiée (Épargne, historique de prêt, statut actif)
✅ Garanties documentées (Garants, Nantissements, documents)
✅ Conditions du prêt calculées et conformes aux politiques
✅ Documents requis collectés
✅ Approbation du comité de prêt obtenue (si requise par l’organisation)
✅ Le Membre comprend les conditions de remboursement

Pendant la création (via API)

✅ En-tête x-idempotency-key fourni
✅ Tous les champs requis dans le corps de la requête
✅ Montant du prêt dans les limites de la politique
✅ Garanties suffisantes pour couvrir le prêt
✅ Le Membre n’a aucun prêt ACTIVE/DEFAULTED existant
✅ L’appel API réussit (réponse 201)

Après le Décaissement

✅ Fonds décaissés au Membre (espèces ou virement bancaire)
✅ Le Membre signe le reçu de Décaissement
✅ Documents de prêt classés
✅ Échéancier fourni au Membre
✅ Membre ajouté à la liste de rappels de paiement
✅ Premier rappel de paiement planifié

Suivi continu

✅ Paiements enregistrés rapidement
✅ Paiements en retard suivis immédiatement
✅ Pénalités appliquées selon la politique
✅ Statut du prêt mis à jour si nécessaire (COMPLETED, DEFAULTED)

Problèmes courants

Le membre a déjà un prêt actif

Erreur : “Organization user already has an active or defaulted loan”Cause : le Membre a actuellement un prêt avec le statut ACTIVE ou DEFAULTEDSolution :

Attendre que le prêt existant soit entièrement remboursé (statut = COMPLETED)
Ou déclarer le prêt existant en défaut si approprié (POST /loans/{id}/default)
Impossible d’avoir plusieurs prêts simultanés par Membre

Garanties insuffisantes

Erreur : “Insufficient security coverage”Cause : valeur totale des garanties < montant du Capital du prêtSolution :

Ajouter plus de Garants
Augmenter la valeur du Nantissement
Réduire le montant du prêt
Exiger un solde d’Épargne plus élevé

Le capital dépasse le maximum autorisé

Erreur : “Principal exceeds max allowed from max loan percentage rule”Cause : montant du prêt > (Épargne du membre × max_loan_percentage)Exemple : Épargne = 100 000, max_loan_percentage = 3.0, maximum autorisé = 300 000Solution :

Réduire le montant du prêt
Demander au Membre d’épargner davantage d’abord
Demander à l’organisation d’augmenter le paramètre max_loan_percentage

La période dépasse le maximum

Erreur : “Loan period cannot exceed X month(s)”Cause : Période du prêt > paramètre max_period de l’organisationSolution :

Réduire la Période du prêt
Demander à l’organisation d’augmenter le paramètre max_period

Besoin d'annuler le prêt après création

Situation : prêt créé, mais le Membre veut annulerSi créé le même jour :

Le Membre peut rembourser immédiatement tout le Capital
Enregistrer le paiement : POST /loans/{id}/repay
Le statut du prêt passe à COMPLETED

Si plusieurs jours/semaines ont déjà passé :

Le Membre doit rembourser selon l’échéancier
Ou négocier une restructuration avec l’agent de crédit
Impossible de supprimer un prêt décaissé (fonds déjà remis)

Les paramètres de prêt ne s'appliquent pas

Problème : les valeurs par défaut des paramètres de l’organisation ne sont pas utiliséesÀ vérifier :

Les loanSettings de l’organisation sont-ils configurés ?
Les champs du corps de requête remplacent-ils les paramètres ?
Vérifier les paramètres avec GET /organizations/{id}

Note : les paramètres du corps de requête ont priorité sur les valeurs par défaut de l’organisation

Amélioration future : workflow en plusieurs étapes

Le statut PENDING existe dans la base de données, mais n’est pas actuellement utilisé. Une future version pourra implémenter :

POST /loans avec status=PENDING (demande de prêt en brouillon)
Endpoint PUT /loans//approve pour changer PENDING → ACTIVE
DELETE /loans/ pour annuler les prêts PENDING
États de workflow et processus d’approbation

Cela permettrait :

Demandes de prêt soumises pour examen
Approbation du comité avant Décaissement
Séparation de la demande et du Décaissement
Annulation des prêts non approuvés

Actuellement : tous les prêts créés via l’API sont immédiatement ACTIVE et décaissés.

Sujets connexes

Créer des prêts

Documentation API détaillée des prêts

Règles de prêt

Calculs d’Intérêt et types d’échéances

Enregistrer les paiements

Comment enregistrer les remboursements de prêt

Prêts en Cours

Surveiller le portefeuille de prêts

​Vue d’ensemble

​Vue d’ensemble du workflow

​Étape 1 : Préparation avant le prêt

​Étape 2 : Création et Décaissement du Prêt

​Requête

​Ce qui se passe automatiquement

​Réponse

​Erreurs

​Étape 3 : Après le Décaissement

​Actions immédiates

​Suivi continu

​Options de frais de Décaissement et de paiement de l’Intérêt

​Options de déduction des frais

​Options de calendrier de paiement de l’Intérêt

​Configuration depuis les paramètres de l’organisation

​Checklist complète du workflow

​Avant la création

​Pendant la création (via API)

​Après le Décaissement

​Suivi continu

​Problèmes courants

​Amélioration future : workflow en plusieurs étapes

​Sujets connexes

Créer des prêts

Règles de prêt

Enregistrer les paiements

Prêts en Cours

Vue d’ensemble

Vue d’ensemble du workflow

Étape 1 : Préparation avant le prêt

Étape 2 : Création et Décaissement du Prêt

Requête

Ce qui se passe automatiquement

Réponse

Erreurs

Étape 3 : Après le Décaissement

Actions immédiates

Suivi continu

Options de frais de Décaissement et de paiement de l’Intérêt

Options de déduction des frais

Options de calendrier de paiement de l’Intérêt

Configuration depuis les paramètres de l’organisation

Checklist complète du workflow

Avant la création

Pendant la création (via API)

Après le Décaissement

Suivi continu

Problèmes courants

Amélioration future : workflow en plusieurs étapes

Sujets connexes