Exécution et réconciliation des paiements

Exécuter un cycle

Lance l'exécution d'un cycle validé. Les paiements sont marqués comme "en_cours" et les données sont préparées pour l'opérateur Mobile Money.

Endpoint

POST /api/paiements/cycles/{id}/execute

Prérequis

• Le cycle doit être en statut valide ou valide_coord
• L'utilisateur doit avoir le rôle ROLE_COORDINATEUR

Exemple de requête

curl -X POST "https://api.pch-sig.org/api/paiements/cycles/550e8400-e29b-41d4-a716-446655440002/execute" \
  -H "Authorization: Bearer <token>"

Réponse

{
  "success": true,
  "message": "3500 paiements envoyés pour traitement",
  "data": {
    "paiements": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440010",
        "codeBeneficiaire": "BEN-001",
        "nomComplet": "Mamadou Diallo",
        "telephone": "+245955123456",
        "compteMobile": "955123456",
        "montant": 25000,
        "operateur": "orange",
        "region": "Oio",
        "secteur": "Farim",
        "codeMenage": "MEN-OIO-001",
        "sexe": "M"
      }
    ],
    "stats": {
      "total": 3500,
      "montantTotal": 87500000,
      "hommes": 1200,
      "femmes": 2300,
      "parOperateur": {
        "orange": 2000,
        "mtn": 1000,
        "wave": 500
      }
    },
    "cycle": {
      "id": "550e8400-e29b-41d4-a716-446655440002",
      "code": "PCH-C002",
      "nom": "Cycle Février 2025",
      "dateExecution": "2025-02-15"
    },
    "programme": {
      "nom": "Programme Capital Humain"
    }
  }
}

---

Export PDF des paiements

Génère les données pour créer le fichier PDF à envoyer à l'opérateur. Met automatiquement les statuts en "en_cours".

Endpoint

POST /api/paiements/cycles/{id}/export-paiements-pdf

Réponse

Même format que l'exécution, avec les données formatées pour génération PDF.

---

Import de réconciliation

Importe le fichier de réconciliation retourné par l'opérateur Mobile Money pour mettre à jour les statuts des paiements.

Endpoint

POST /api/paiements/cycles/{id}/import-reconciliation

Prérequis

• Le cycle doit être en statut en_cours
• L'utilisateur doit avoir le rôle ROLE_TM_SPECIALIST

Corps de la requête

{
  "reconciliations": [
    {
      "code_beneficiaire": "BEN-001",
      "statut": "reussi",
      "transaction_id": "TXN-OP-123456"
    },
    {
      "telephone": "+245955654321",
      "statut": "echoue",
      "motif_echec": "Numéro invalide"
    },
    {
      "id": "550e8400-e29b-41d4-a716-446655440010",
      "statut": "success",
      "transaction_id": "TXN-OP-123457"
    }
  ]
}

Champs de réconciliation

Champ	Type	Requis	Description
id	UUID	Non*	ID du paiement
code_beneficiaire	string	Non*	Code du bénéficiaire
telephone	string	Non*	Numéro de téléphone
compte_mobile	string	Non*	Compte Mobile Money
statut	string	Oui	reussi/succes/success ou echoue/echec/failed
transaction_id	string	Non	Référence transaction opérateur
motif_echec	string	Non	Raison de l'échec

*Au moins un identifiant est requis (id, code_beneficiaire, telephone ou compte_mobile)

Réponse

{
  "success": true,
  "data": {
    "total": 3500,
    "traites": 3500,
    "reussis": 3450,
    "echoues": 50,
    "non_trouves": 0,
    "erreurs": []
  }
}

Valeurs de statut acceptées

Succès : reussi, succes, success, ok, 1, true, paid

Échec : Toute autre valeur est considérée comme un échec

Codes de réponse

Code	Description
200	Import réussi
400	Cycle pas en cours ou données invalides
401	Non authentifié
403	Non autorisé
404	Cycle non trouvé