Operator Accounts API

The Operator Accounts API allows managing Mobile Money operator accounts and tracking their financial movements.

Overview

Endpoint	Method	Description
`/api/comptes-operateurs`	GET	List of accounts
`/api/comptes-operateurs/{id}`	GET	Account details
`/api/comptes-operateurs`	POST	Create an account
`/api/comptes-operateurs/{id}`	PUT	Modify an account
`/api/comptes-operateurs/{id}`	DELETE	Delete an account
`/api/comptes-operateurs/operateurs`	GET	List of operators
`/api/comptes-operateurs/stats`	GET	Global statistics
`/api/comptes-operateurs/alertes`	GET	Balance alerts
`/api/comptes-operateurs/by-projet-operateur`	GET	Account by project/operator
`/api/comptes-operateurs/{id}/depots`	POST	Record a deposit
`/api/comptes-operateurs/{id}/mouvements`	GET	Movement history
`/api/comptes-operateurs/{id}/stats`	GET	Account statistics
`/api/comptes-operateurs/{id}/recalculer`	POST	Recalculate balance

List operator accounts

Endpoint

GET /api/comptes-operateurs

Query parameters

Parameter	Type	Required	Description
`page`	int	No	Page number (default: 1)
`limit`	int	No	Items per page (default: 20)
`operateur`	string	No	Filter by operator (orange_money, mtn_money)
`projet`	UUID	No	Filter by project
`statut`	string	No	Filter by status (actif, inactif)
`search`	string	No	Text search

Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "OM-PCH-001",
      "operateur": "orange_money",
      "operateurLabel": "Orange Money",
      "numeroCompte": "955123456",
      "nomCompte": "PCH Payments Oio",
      "projet": {
        "id": "...",
        "nom": "PCH Guinea-Bissau"
      },
      "solde": 125000000,
      "soldeMinimum": 10000000,
      "devise": "XOF",
      "statut": "actif",
      "alerteSolde": false,
      "dernierDepot": "2025-03-10T14:30:00+00:00",
      "dernierPaiement": "2025-03-15T09:00:00+00:00",
      "createdAt": "2025-01-01T08:00:00+00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 8,
    "pages": 1
  }
}

Account details

Endpoint

GET /api/comptes-operateurs/{id}

Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "OM-PCH-001",
    "operateur": "orange_money",
    "operateurLabel": "Orange Money",
    "numeroCompte": "955123456",
    "nomCompte": "PCH Payments Oio",
    "description": "Main account for Oio region payments",
    "projet": {
      "id": "...",
      "nom": "PCH Guinea-Bissau",
      "code": "PCH-GW"
    },
    "solde": 125000000,
    "soldeMinimum": 10000000,
    "seuilAlerte": 15000000,
    "devise": "XOF",
    "statut": "actif",
    "alerteSolde": false,
    "contacts": {
      "responsable": "Mamadou Diallo",
      "telephone": "+245955789012",
      "email": "m.diallo@pch.gw"
    },
    "dernierDepot": {
      "date": "2025-03-10T14:30:00+00:00",
      "montant": 50000000,
      "reference": "DEP-2025-0045"
    },
    "dernierPaiement": {
      "date": "2025-03-15T09:00:00+00:00",
      "montant": 12500000,
      "cycleId": "..."
    },
    "statsResume": {
      "totalDepots": 450000000,
      "totalPaiements": 325000000,
      "nombrePaiements": 13000
    },
    "createdAt": "2025-01-01T08:00:00+00:00",
    "updatedAt": "2025-03-15T09:00:00+00:00"
  }
}

Create an account

Endpoint

POST /api/comptes-operateurs

Request body

{
  "operateur": "orange_money",
  "numeroCompte": "955123456",
  "nomCompte": "PCH Payments Oio",
  "description": "Main account for Oio region payments",
  "projetId": "550e8400-e29b-41d4-a716-446655440001",
  "soldeInitial": 0,
  "soldeMinimum": 10000000,
  "seuilAlerte": 15000000,
  "contacts": {
    "responsable": "Mamadou Diallo",
    "telephone": "+245955789012",
    "email": "m.diallo@pch.gw"
  }
}

Available operators

Operator	Label	Description
`orange_money`	Orange Money	Orange Money Guinea-Bissau
`mtn_money`	MTN Mobile Money	MTN Mobile Money
`wave`	Wave	Wave
`free_money`	Free Money	Free Money

Response

{
  "success": true,
  "message": "Operator account created successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "OM-PCH-001"
  }
}

List of operators

Endpoint

GET /api/comptes-operateurs/operateurs

Response

{
  "success": true,
  "data": [
    {
      "value": "orange_money",
      "label": "Orange Money",
      "logo": "/images/operators/orange.png",
      "actif": true
    },
    {
      "value": "mtn_money",
      "label": "MTN Mobile Money",
      "logo": "/images/operators/mtn.png",
      "actif": true
    },
    {
      "value": "wave",
      "label": "Wave",
      "logo": "/images/operators/wave.png",
      "actif": true
    }
  ]
}

Global statistics

Endpoint

GET /api/comptes-operateurs/stats

Query parameters

Parameter	Type	Required	Description
`projet`	UUID	No	Filter by project
`dateDebut`	date	No	Start date
`dateFin`	date	No	End date

Response

{
  "success": true,
  "data": {
    "totalComptes": 8,
    "comptesActifs": 7,
    "soldeTotal": 850000000,
    "devise": "XOF",
    "parOperateur": [
      {
        "operateur": "orange_money",
        "label": "Orange Money",
        "comptes": 4,
        "solde": 500000000
      },
      {
        "operateur": "mtn_money",
        "label": "MTN Mobile Money",
        "comptes": 3,
        "solde": 300000000
      }
    ],
    "alertes": {
      "soldeFaible": 1,
      "inactifs": 1
    },
    "activiteRecente": {
      "depotsJour": 2,
      "montantDepotsJour": 75000000,
      "paiementsJour": 1500,
      "montantPaiementsJour": 37500000
    }
  }
}

Balance alerts

Endpoint

GET /api/comptes-operateurs/alertes

Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "code": "OM-PCH-002",
      "nomCompte": "PCH Payments Bafata",
      "operateur": "orange_money",
      "solde": 8000000,
      "soldeMinimum": 10000000,
      "deficit": 2000000,
      "typeAlerte": "solde_critique",
      "message": "Balance below minimum required"
    }
  ]
}

Account by project and operator

Endpoint

GET /api/comptes-operateurs/by-projet-operateur

Query parameters

Parameter	Type	Required	Description
`projetId`	UUID	Yes	Project ID
`operateur`	string	Yes	Operator code

Response

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "code": "OM-PCH-001",
    "solde": 125000000,
    "operateur": "orange_money"
  }
}

Record a deposit

Endpoint

POST /api/comptes-operateurs/{id}/depots

Request body

{
  "montant": 50000000,
  "reference": "VIR-2025-0045",
  "dateDepot": "2025-03-15",
  "source": "Bank transfer",
  "notes": "Provisioning for March 2025 cycle",
  "pieceJustificative": "optional_file_id"
}

Response

{
  "success": true,
  "message": "Deposit recorded successfully",
  "data": {
    "depotId": "550e8400-e29b-41d4-a716-446655440010",
    "reference": "DEP-2025-0046",
    "montant": 50000000,
    "nouveauSolde": 175000000
  }
}

Movement history

Endpoint

GET /api/comptes-operateurs/{id}/mouvements

Query parameters

Parameter	Type	Required	Description
`page`	int	No	Page number
`limit`	int	No	Items per page
`type`	string	No	Movement type (depot, paiement, ajustement)
`dateDebut`	date	No	Start date
`dateFin`	date	No	End date

Response

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440020",
      "type": "depot",
      "typeLabel": "Deposit",
      "reference": "DEP-2025-0046",
      "montant": 50000000,
      "soldeAvant": 125000000,
      "soldeApres": 175000000,
      "date": "2025-03-15T10:30:00+00:00",
      "description": "March 2025 provisioning",
      "createdBy": {
        "id": "...",
        "nom": "Admin User"
      }
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440021",
      "type": "paiement",
      "typeLabel": "Payment",
      "reference": "CYC-2025-003",
      "montant": -12500000,
      "soldeAvant": 175000000,
      "soldeApres": 162500000,
      "date": "2025-03-15T14:00:00+00:00",
      "description": "March 2025 payment cycle - 500 beneficiaries",
      "cycleId": "..."
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 156,
    "pages": 8
  }
}

Account statistics

Endpoint

GET /api/comptes-operateurs/{id}/stats

Query parameters

Parameter	Type	Required	Description
`periode`	string	No	month, quarter, year (default: month)

Response

{
  "success": true,
  "data": {
    "compte": {
      "id": "...",
      "code": "OM-PCH-001",
      "soldeActuel": 162500000
    },
    "periode": {
      "debut": "2025-03-01",
      "fin": "2025-03-15"
    },
    "resume": {
      "totalDepots": 100000000,
      "nombreDepots": 2,
      "totalPaiements": 62500000,
      "nombrePaiements": 2500,
      "soldeDebut": 125000000,
      "soldeFin": 162500000
    },
    "evolution": [
      {"date": "2025-03-01", "solde": 125000000},
      {"date": "2025-03-05", "solde": 112500000},
      {"date": "2025-03-10", "solde": 162500000},
      {"date": "2025-03-15", "solde": 162500000}
    ],
    "moyennePaiementJour": 4166667
  }
}

Recalculate balance

Endpoint

POST /api/comptes-operateurs/{id}/recalculer

Description

Recalculates the account balance based on all recorded movements. Useful in case of desynchronization.

Response

{
  "success": true,
  "message": "Balance recalculated successfully",
  "data": {
    "ancienSolde": 160000000,
    "nouveauSolde": 162500000,
    "difference": 2500000,
    "nombreMouvements": 156
  }
}

warning

This operation may modify the displayed balance. It is recommended only in case of detected inconsistency.

Overview​

List operator accounts​

Endpoint​

Query parameters​

Response​

Account details​

Endpoint​

Response​

Create an account​

Endpoint​

Request body​

Available operators​

Response​

List of operators​

Endpoint​

Response​

Global statistics​

Endpoint​

Query parameters​

Response​

Balance alerts​

Endpoint​

Response​

Account by project and operator​

Endpoint​

Query parameters​

Response​

Record a deposit​

Endpoint​

Request body​

Response​

Movement history​

Endpoint​

Query parameters​

Response​

Account statistics​

Endpoint​

Query parameters​

Response​

Recalculate balance​

Endpoint​

Description​

Response​

Overview

List operator accounts

Endpoint

Query parameters

Response

Account details

Endpoint

Response

Create an account

Endpoint

Request body

Available operators

Response

List of operators

Endpoint

Response

Global statistics

Endpoint

Query parameters

Response

Balance alerts

Endpoint

Response

Account by project and operator

Endpoint

Query parameters

Response

Record a deposit

Endpoint

Request body

Response

Movement history

Endpoint

Query parameters

Response

Account statistics

Endpoint

Query parameters

Response

Recalculate balance

Endpoint

Description

Response