Paiements Community Workers

Cette page documente la gestion des paiements des Community Workers (Cuidadoras).

Nouveau systeme de paiement (via Cycle)

Depuis la version recente, les paiements des cuidadoras sont geres via l'entite Paiement standard, integree aux cycles de paiement du programme.

Principe

Les cuidadoras sont enregistrees comme beneficiaires avec la categorie cuidador. Leurs paiements suivent le meme workflow que les autres beneficiaires :

┌────────────────────────────────────────────────────────────────────────┐
│                      CYCLE DE PAIEMENT                                  │
│  ┌──────────────────────────────────────────────────────────────────┐  │
│  │ Code: C025                                                        │  │
│  │ Periode: Juillet 2026                                             │  │
│  │ Programme: Agents communautaires                                  │  │
│  └──────────────────────────────────────────────────────────────────┘  │
│                                    │                                    │
│      ┌─────────────────────────────┼─────────────────────────────┐     │
│      ▼                             ▼                             ▼     │
│ ┌──────────────┐           ┌──────────────┐            ┌──────────────┐│
│ │ Paiement CW  │           │ Paiement CW  │            │ Paiement CW  ││
│ │ Agent       │           │ Agent       │            │ Agent       ││
│ │ 150,000 XOF  │           │ 150,000 XOF  │            │ 150,000 XOF  ││
│ │ Mobile Money │           │ Mobile Money │            │ Mobile Money ││
│ │ Paye ✓       │           │ En attente   │            │ Rejete       ││
│ └──────────────┘           └──────────────┘            └──────────────┘│
└────────────────────────────────────────────────────────────────────────┘

Endpoints principaux

Endpoint	Methode	Description
`/api/community-workers/paiements`	GET	Liste des paiements cuidadors
`/api/community-workers/paiements/stats`	GET	Statistiques des paiements

Liste des paiements cuidadors

Endpoint

GET /api/community-workers/paiements

Parametres de requete

Parametre	Type	Description
`cycle`	UUID	Filtrer par cycle
`region`	UUID	Filtrer par region
`statut`	string	Filtrer par statut
`communityWorker`	UUID	Filtrer par cuidador
`page`	int	Page (defaut: 1)
`limit`	int	Elements par page (defaut: 20)

Reponse

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "TXN-2026-07-00001",
      "communityWorker": {
        "id": "...",
        "code": "CW-OIO-00123",
        "nomComplet": "Maria Silva",
        "region": "Oio"
      },
      "cycle": {
        "id": "...",
        "code": "C025",
        "libelle": "Paiement Juillet 2026"
      },
      "montant": "150000",
      "methodePaiement": "mobile_money",
      "operateur": "telecel",
      "statut": "paye",
      "datePaiement": "2026-07-15",
      "referenceOperateur": "TXN-TEL-123456",
      "createdAt": "2026-07-10T08:00:00+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "pages": 8
  }
}

Statistiques des paiements

Endpoint

GET /api/community-workers/paiements/stats

Reponse

{
  "success": true,
  "data": {
    "total": 450,
    "montantTotal": "67500000",
    "parStatut": {
      "paye": {
        "count": 380,
        "montant": "57000000"
      },
      "en_attente": {
        "count": 50,
        "montant": "7500000"
      },
      "rejete": {
        "count": 20,
        "montant": "3000000"
      }
    },
    "parRegion": [
      {
        "regionId": "...",
        "regionNom": "Oio",
        "count": 150,
        "montant": "22500000"
      },
      {
        "regionId": "...",
        "regionNom": "Bafata",
        "count": 120,
        "montant": "18000000"
      }
    ]
  }
}

Statuts de paiement

Statut	Description
`en_attente`	Paiement en attente de traitement
`en_cours`	Paiement en cours de traitement par l'operateur
`paye`	Paiement effectue avec succes
`rejete`	Paiement rejete (numero invalide, etc.)
`annule`	Paiement annule

Workflow de paiement cuidadors

┌──────────────┐     ┌───────────┐     ┌─────────┐     ┌────────┐
│  En attente  │ --> │ En cours  │ --> │  Paye   │     │        │
└──────────────┘     └───────────┘     └─────────┘     │        │
       │                   │                           │        │
       │                   └──────────────────────────►│ Rejete │
       │                                               │        │
       └──────────────────────────────────────────────►│        │
                                                       └────────┘

En attente : Paiement cree dans le cycle, en attente d'export vers l'operateur
En cours : Fichier transmis a l'operateur, traitement en cours
Paye : Confirmation de paiement recue
Rejete : Echec du paiement (numero invalide, solde insuffisant, etc.)

Ancien systeme de paiement (legacy)

Deprecie

L'ancien systeme base sur CWFichePaiement et CWLotPaiement est deprecie. Les nouveaux paiements doivent utiliser le systeme de cycles standard.

Architecture des paiements (legacy)

┌─────────────────────────────────────────────────────────────────────────┐
│                          LOT DE PAIEMENT                                │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ Reference: LOT-2026-06-001                                      │    │
│  │ Periode: Juin 2026                                              │    │
│  │ Statut: en_cours                                                │    │
│  │ Montant total: 15,000,000 XOF                                   │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                    │                                     │
│      ┌─────────────────────────────┼─────────────────────────────┐      │
│      ▼                             ▼                             ▼      │
│ ┌──────────────┐           ┌──────────────┐            ┌──────────────┐ │
│ │ Fiche #1     │           │ Fiche #2     │            │ Fiche #3     │ │
│ │ PMT-2606-001 │           │ PMT-2606-002 │            │ PMT-2606-003 │ │
│ │ Agent       │           │ Mamadou D.   │            │ Agent       │ │
│ │ 100,000 XOF  │           │ 100,000 XOF  │            │ 100,000 XOF  │ │
│ │ Paye ✓       │           │ En cours     │            │ Bloque       │ │
│ └──────────────┘           └──────────────┘            └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘

Fiche de paiement (CWFichePaiement)

Une fiche de paiement represente le paiement mensuel d'un Community Worker.

Modele de donnees

Champ	Type	Description
`id`	UUID	Identifiant unique
`code`	string	Code unique (format: PMT-YYMM-XXXXX)
`communityWorker`	object	Community worker concerne
`periode`	string	Periode textuelle (ex: "Juin 2026")
`annee`	int	Annee (2020-2100)
`mois`	int	Mois (1-12)
`salaireBase`	decimal	Salaire de base
`primeTerrain`	decimal	Prime de terrain
`primePerformance`	decimal	Prime de performance
`retenues`	decimal	Retenues eventuelles
`brut`	decimal	Total brut (calcule)
`netAPayer`	decimal	Net a payer (calcule)
`modePaiement`	string	Mode de paiement
`numeroMobileMoney`	string	Numero Mobile Money
`compteBancaire`	string	Compte bancaire
`referenceOperateur`	string	Reference de l'operateur
`statut`	string	Statut de la fiche
`motifBlocage`	text	Motif en cas de blocage
`datePaiement`	datetime	Date effective du paiement
`lot`	object	Lot de paiement associe

Statuts de fiche

Statut	Description
`brouillon`	Fiche en cours d'edition
`en_attente`	Fiche validee, en attente de traitement
`en_cours`	Paiement en cours de traitement
`paye`	Paiement effectue avec succes
`bloque`	Paiement bloque (motif requis)

Modes de paiement

Mode	Description
`mobile_money`	Paiement par Mobile Money
`virement`	Virement bancaire
`especes`	Paiement en especes

Calcul du net a payer

Le net a payer est calcule automatiquement :

Brut = Salaire Base + Prime Terrain + Prime Performance
Net = max(0, Brut - Retenues)

Lot de paiement (CWLotPaiement)

Un lot de paiement regroupe plusieurs fiches de paiement pour un traitement groupe.

Modele de donnees

Champ	Type	Description
`id`	UUID	Identifiant unique
`reference`	string	Reference du lot
`annee`	int	Annee
`mois`	int	Mois
`statut`	string	Statut du lot
`nbFiches`	int	Nombre de fiches
`montantTotal`	decimal	Montant total
`fiches`	array	Liste des fiches

Statuts de lot

Statut	Description
`brouillon`	Lot en preparation
`valide`	Lot valide, pret pour transmission
`transmis`	Transmis a l'operateur
`en_cours`	Traitement en cours
`termine`	Tous les paiements effectues
`cloture`	Lot cloture definitivement

Endpoints API

Fiches de paiement

Endpoint	Methode	Description
`/api/cw-paiements/fiches`	GET	Liste des fiches
`/api/cw-paiements/fiches/{id}`	GET	Detail d'une fiche
`/api/cw-paiements/fiches/{id}`	PUT, PATCH	Modifier les montants et le mode de paiement
`/api/cw-paiements/fiches/{id}/marquer-paye`	POST	Marquer comme paye
`/api/cw-paiements/fiches/{id}/bloquer`	POST	Bloquer une fiche (`motif` obligatoire)
`/api/cw-paiements/fiches/{id}/debloquer`	POST	Debloquer une fiche
`/api/cw-paiements/generer`	POST	Generer les fiches du mois
`/api/cw-paiements/stats`	GET	Statistiques

Il n'y a pas de création unitaire de fiche : elles sont produites par la génération mensuelle.

Lots de paiement

Endpoint	Methode	Description
`/api/cw-paiements/lots`	GET	Liste des lots
`/api/cw-paiements/lots`	POST	Creer un lot (`regionId`, `annee`, `mois` obligatoires)
`/api/cw-paiements/lots/{id}`	GET	Detail d'un lot
`/api/cw-paiements/lots/{id}/soumettre`	POST	Soumettre pour validation
`/api/cw-paiements/lots/{id}/valider`	POST	Valider le lot
`/api/cw-paiements/lots/{id}/rejeter`	POST	Rejeter le lot (`motif` obligatoire)
`/api/cw-paiements/lots/{id}/executer`	POST	Exécuter le lot

Exemple : Generer les fiches du mois

Requete

POST /api/cw-paiements/generer

{
  "annee": 2026,
  "mois": 6,
  "salaireBase": "50000",
  "primeTerrain": "10000"
}

Tous les champs sont optionnels : par défaut le mois en cours, 50 000 de salaire de base et 10 000 de prime terrain. Une fiche déjà existante pour le mois est ignorée.

Reponse

{
  "success": true,
  "message": "45 fiches créées, 5 ignorées (déjà existantes)",
  "data": {
    "created": 45,
    "skipped": 5
  }
}

Exemple : Marquer une fiche comme payee

Requete

POST /api/cw-paiements/fiches/{id}/marquer-paye

{
  "referenceOperateur": "TXN-2026-06-12345"
}

Reponse

{
  "success": true,
  "message": "Fiche marquée comme payée",
  "data": { "id": "…", "statut": "paye", "referenceOperateur": "TXN-2026-06-12345" }
}

Workflow de paiement

┌──────────┐     ┌───────────┐     ┌─────────┐     ┌────────┐
│ Brouillon│ --> │ En attente│ --> │ En cours│ --> │  Paye  │
└──────────┘     └───────────┘     └─────────┘     └────────┘
                       │
                       ▼
                 ┌─────────┐
                 │ Bloque  │ <-- (motif requis)
                 └─────────┘

Brouillon : Fiche creee, montants en cours d'edition
En attente : Fiche validee, prete pour integration dans un lot
En cours : Lot transmis a l'operateur, paiement en traitement
Paye : Paiement recu par le beneficiaire
Bloque : Probleme identifie (numero invalide, compte ferme, etc.)

Nouveau systeme de paiement (via Cycle)​

Principe​

Endpoints principaux​

Liste des paiements cuidadors​

Endpoint​

Parametres de requete​

Reponse​

Statistiques des paiements​

Endpoint​

Reponse​

Statuts de paiement​

Workflow de paiement cuidadors​

Ancien systeme de paiement (legacy)​

Architecture des paiements (legacy)​

Fiche de paiement (CWFichePaiement)​

Modele de donnees​

Statuts de fiche​

Modes de paiement​

Calcul du net a payer​

Lot de paiement (CWLotPaiement)​

Modele de donnees​

Statuts de lot​

Endpoints API​

Fiches de paiement​

Lots de paiement​

Exemple : Generer les fiches du mois​

Requete​

Reponse​

Exemple : Marquer une fiche comme payee​

Requete​

Reponse​

Workflow de paiement​

Nouveau systeme de paiement (via Cycle)

Principe

Endpoints principaux

Liste des paiements cuidadors

Endpoint

Parametres de requete

Reponse

Statistiques des paiements

Endpoint

Reponse

Statuts de paiement

Workflow de paiement cuidadors

Ancien systeme de paiement (legacy)

Architecture des paiements (legacy)

Fiche de paiement (CWFichePaiement)

Modele de donnees

Statuts de fiche

Modes de paiement

Calcul du net a payer

Lot de paiement (CWLotPaiement)

Modele de donnees

Statuts de lot

Endpoints API

Fiches de paiement

Lots de paiement

Exemple : Generer les fiches du mois

Requete

Reponse

Exemple : Marquer une fiche comme payee

Requete

Reponse

Workflow de paiement