Community Workers Payments

This page documents the payment management for Community Workers, including monthly payment slips and payment batches.

---

Payment Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                          PAYMENT BATCH                                   │
│  ┌─────────────────────────────────────────────────────────────────┐    │
│  │ Reference: LOT-2026-06-001                                      │    │
│  │ Period: June 2026                                               │    │
│  │ Status: in_progress                                             │    │
│  │ Total amount: 15,000,000 XOF                                    │    │
│  └─────────────────────────────────────────────────────────────────┘    │
│                                    │                                     │
│      ┌─────────────────────────────┼─────────────────────────────┐      │
│      ▼                             ▼                             ▼      │
│ ┌──────────────┐           ┌──────────────┐            ┌──────────────┐ │
│ │ Slip #1      │           │ Slip #2      │            │ Slip #3      │ │
│ │ PMT-2606-001 │           │ PMT-2606-002 │            │ PMT-2606-003 │ │
│ │ Agent       │           │ Agent       │            │ Agent       │ │
│ │ 100,000 XOF  │           │ 100,000 XOF  │            │ 100,000 XOF  │ │
│ │ Paid ✓       │           │ In progress  │            │ Blocked      │ │
│ └──────────────┘           └──────────────┘            └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘

---

Payment Slip (CWFichePaiement)

A payment slip represents a Community Worker's monthly payment.

Data Model

Field	Type	Description
id	UUID	Unique identifier
code	string	Unique code (format: PMT-YYMM-XXXXX)
communityWorker	object	Related community worker
periode	string	Period text (e.g., "June 2026")
annee	int	Year (2020-2100)
mois	int	Month (1-12)
salaireBase	decimal	Base salary
primeTerrain	decimal	Field bonus
primePerformance	decimal	Performance bonus
retenues	decimal	Deductions
brut	decimal	Gross total (calculated)
netAPayer	decimal	Net payable (calculated)
modePaiement	string	Payment method
numeroMobileMoney	string	Mobile Money number
compteBancaire	string	Bank account
referenceOperateur	string	Operator reference
statut	string	Slip status
motifBlocage	text	Blocking reason
datePaiement	datetime	Actual payment date
lot	object	Associated payment batch

Slip Statuses

Status	Description
brouillon	Slip being edited
en_attente	Validated slip, awaiting processing
en_cours	Payment being processed
paye	Payment successfully completed
bloque	Payment blocked (reason required)

Payment Methods

Method	Description
mobile_money	Mobile Money payment
virement	Bank transfer
especes	Cash payment

---

Net Payment Calculation

The net payable is calculated automatically:

Gross = Base Salary + Field Bonus + Performance Bonus
Net = max(0, Gross - Deductions)

---

Payment Batch (CWLotPaiement)

A payment batch groups multiple payment slips for batch processing.

Data Model

Field	Type	Description
id	UUID	Unique identifier
reference	string	Batch reference
annee	int	Year
mois	int	Month
statut	string	Batch status
nbFiches	int	Number of slips
montantTotal	decimal	Total amount
fiches	array	List of slips

Batch Statuses

Status	Description
brouillon	Batch being prepared
valide	Validated batch, ready for transmission
transmis	Transmitted to operator
en_cours	Processing in progress
termine	All payments completed
cloture	Batch permanently closed

---

API Endpoints

Payment Slips

Endpoint	Method	Description
/api/cw-paiements/fiches	GET	List slips
/api/cw-paiements/fiches/{id}	GET	Slip details
/api/cw-paiements/fiches/{id}	PUT, PATCH	Update amounts and payment method
/api/cw-paiements/fiches/{id}/marquer-paye	POST	Mark as paid
/api/cw-paiements/fiches/{id}/bloquer	POST	Block a slip (motif required)
/api/cw-paiements/fiches/{id}/debloquer	POST	Unblock a slip
/api/cw-paiements/generer	POST	Generate the month's slips
/api/cw-paiements/stats	GET	Statistics

There is no single-slip creation: slips are produced by the monthly generation.

Payment Batches

Endpoint	Method	Description
/api/cw-paiements/lots	GET	List batches
/api/cw-paiements/lots	POST	Create a batch (regionId, annee, mois required)
/api/cw-paiements/lots/{id}	GET	Batch details
/api/cw-paiements/lots/{id}/soumettre	POST	Submit for validation
/api/cw-paiements/lots/{id}/valider	POST	Validate the batch
/api/cw-paiements/lots/{id}/rejeter	POST	Reject the batch (motif required)
/api/cw-paiements/lots/{id}/executer	POST	Execute the batch

---

Example: Generate Monthly Slips

POST /api/cw-paiements/generer

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

All fields are optional: by default the current month, a base salary of 50,000 and a field bonus of 10,000. A slip that already exists for the month is skipped.

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

---

Example: Mark Slip as Paid

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

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

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

---

Payment Workflow

┌──────────┐     ┌───────────┐     ┌─────────┐     ┌────────┐
│  Draft   │ --> │  Pending  │ --> │ In prog │ --> │  Paid  │
└──────────┘     └───────────┘     └─────────┘     └────────┘
                       │
                       ▼
                 ┌─────────┐
                 │ Blocked │ <-- (reason required)
                 └─────────┘

1. Draft: Slip created, amounts being edited
2. Pending: Slip validated, ready for batch integration
3. In progress: Batch transmitted to operator, payment being processed
4. Paid: Payment received by beneficiary
5. Blocked: Issue identified (invalid number, closed account, etc.)