Cycle Payments

Endpoints for managing individual payments within a cycle.

GET /api/cycles/{id}/paiements

Retrieves the list of payments for a cycle.

Endpoint

GET /api/cycles/{id}/paiements

Headers

Header	Value	Required
Authorization	Bearer {token}	Yes

Query Parameters

Parameter	Type	Description
page	integer	Page number
itemsPerPage	integer	Items per page
statut	string	Filter by status
search	string	Search by beneficiary name or code

Payment Statuses

Status	Description
brouillon	In preparation
en_attente	Submitted, awaiting RAF validation
valide_raf	Validated by RAF
valide_coord	Validated by Coordinator, ready
en_cours	Execution in progress
execute	Successfully executed
echoue	Payment failed
rejete_raf	Rejected by RAF
rejete_coord	Rejected by Coordinator
annule	Cancelled

Success Response

Code: 200 OK

{
    "@context": "/api/contexts/Paiement",
    "@id": "/api/cycles/770e8400-e29b-41d4-a716-446655440001/paiements",
    "@type": "hydra:Collection",
    "hydra:totalItems": 850,
    "hydra:member": [
        {
            "@id": "/api/paiements/880e8400-e29b-41d4-a716-446655440001",
            "@type": "Paiement",
            "id": "880e8400-e29b-41d4-a716-446655440001",
            "beneficiaire": {
                "@id": "/api/beneficiaires/550e8400-e29b-41d4-a716-446655440000",
                "codeBeneficiaire": "BEN-2024-00001",
                "nomComplet": "Fatou Diallo",
                "telephone": "771234567"
            },
            "montant": "25000.00",
            "montantNet": "24750.00",
            "fraisTransaction": "250.00",
            "statut": "execute",
            "statutLabel": "Exécuté",
            "methodePaiement": "orange_money",
            "operateur": "Orange Money",
            "referenceTransaction": "OM-2024-001234",
            "dateExecution": "2024-01-15T14:30:00+00:00",
            "dateConfirmation": "2024-01-15T14:30:05+00:00",
            "tauxConformite": "95.00",
            "estArriere": false
        }
    ],
    "hydra:view": {
        "@id": "/api/cycles/770e8400.../paiements?page=1",
        "hydra:first": "...?page=1",
        "hydra:last": "...?page=29",
        "hydra:next": "...?page=2"
    }
}

---

GET /api/paiements/{id}

Retrieves the details of a payment.

Endpoint

GET /api/paiements/{id}

Success Response

Code: 200 OK

{
    "@id": "/api/paiements/880e8400-e29b-41d4-a716-446655440001",
    "@type": "Paiement",
    "id": "880e8400-e29b-41d4-a716-446655440001",
    "beneficiaire": {
        "@id": "/api/beneficiaires/550e8400-e29b-41d4-a716-446655440000",
        "codeBeneficiaire": "BEN-2024-00001",
        "nomComplet": "Fatou Diallo",
        "telephone": "771234567",
        "modePaiement": "orange_money",
        "compteMobile": "771234567"
    },
    "cycle": {
        "@id": "/api/cycles/770e8400-e29b-41d4-a716-446655440001",
        "code": "CYC-2024-001",
        "nom": "Cycle Janvier 2024"
    },
    "montant": "25000.00",
    "montantNet": "24750.00",
    "fraisTransaction": "250.00",
    "statut": "execute",
    "methodePaiement": "orange_money",
    "operateur": "Orange Money",
    "referenceTransaction": "OM-2024-001234",
    "referenceExterne": "EXT-REF-001",
    "dateSoumission": "2024-01-15T10:00:00+00:00",
    "dateExecution": "2024-01-15T14:30:00+00:00",
    "dateConfirmation": "2024-01-15T14:30:05+00:00",
    "nbTentatives": 1,
    "codeReponse": "200",
    "messageReponse": "Transaction réussie",
    "tauxConformite": "95.00",
    "alertesConditionnalite": null,
    "datePrevue": "2024-01-15T00:00:00+00:00",
    "joursRetard": 0,
    "estArriere": false,
    "valideParRaf": {
        "email": "raf@pch-sig.sn",
        "nom": "RAF PCH"
    },
    "dateValidationRaf": "2024-01-15T11:00:00+00:00",
    "valideParCoord": {
        "email": "coord@pch-sig.sn",
        "nom": "Coordinateur PCH"
    },
    "dateValidationCoord": "2024-01-15T12:00:00+00:00",
    "historiqueValidation": [
        {
            "action": "soumission",
            "user": "agent@pch-sig.sn",
            "userName": "Agent Terrain",
            "date": "2024-01-15T10:00:00+00:00",
            "details": "Paiement soumis pour validation"
        },
        {
            "action": "validation_raf",
            "user": "raf@pch-sig.sn",
            "userName": "RAF PCH",
            "date": "2024-01-15T11:00:00+00:00",
            "details": "Validé par RAF"
        },
        {
            "action": "validation_coord",
            "user": "coord@pch-sig.sn",
            "userName": "Coordinateur PCH",
            "date": "2024-01-15T12:00:00+00:00",
            "details": "Validé par Coordinateur"
        }
    ]
}

---

POST /api/paiements/{id}/soumettre

Submits a payment for validation.

Endpoint

POST /api/paiements/{id}/soumettre

Success Response

Code: 200 OK

{
    "success": true,
    "statut": "en_attente",
    "message": "Paiement soumis pour validation"
}

---

POST /api/paiements/{id}/valider-raf

Validation by the RAF (Administrative and Financial Manager).

Endpoint

POST /api/paiements/{id}/valider-raf

Request Body

{
    "commentaire": "Validation conforme"
}

Success Response

Code: 200 OK

{
    "success": true,
    "statut": "valide_raf",
    "message": "Paiement validé par RAF"
}

---

POST /api/paiements/{id}/rejeter-raf

Rejection by the RAF.

Endpoint

POST /api/paiements/{id}/rejeter-raf

Request Body

{
    "motif": "Numéro de téléphone invalide"
}

---

POST /api/paiements/{id}/valider-coordinateur

Validation by the Coordinator.

Endpoint

POST /api/paiements/{id}/valider-coordinateur

Request Body

{
    "commentaire": "Approuvé pour exécution"
}

---

POST /api/paiements/{id}/executer

Initiates payment execution.

Endpoint

POST /api/paiements/{id}/executer

Prerequisites

The payment must have the status valide_coord.

Success Response

Code: 200 OK

{
    "success": true,
    "statut": "execute",
    "referenceTransaction": "OM-2024-001234",
    "dateExecution": "2024-01-15T14:30:00+00:00",
    "message": "Paiement exécuté avec succès"
}

Failure Response

Code: 200 OK (the API always returns 200, the status indicates failure)

{
    "success": false,
    "statut": "echoue",
    "codeReponse": "INSUFFICIENT_BALANCE",
    "messageReponse": "Solde insuffisant sur le compte opérateur",
    "nbTentatives": 1
}

---

Complete Examples

JavaScript

class PaiementsAPI {
    constructor(token) {
        this.token = token;
        this.baseUrl = 'https://sig.ucp-pch.org/api';
    }

    async getPaiements(cycleId, filters = {}) {
        const params = new URLSearchParams(filters);
        const response = await fetch(
            `${this.baseUrl}/cycles/${cycleId}/paiements?${params}`,
            {
                headers: { 'Authorization': `Bearer ${this.token}` }
            }
        );
        return response.json();
    }

    async soumettre(paiementId) {
        const response = await fetch(
            `${this.baseUrl}/paiements/${paiementId}/soumettre`,
            {
                method: 'POST',
                headers: { 'Authorization': `Bearer ${this.token}` }
            }
        );
        return response.json();
    }

    async validerRaf(paiementId, commentaire) {
        const response = await fetch(
            `${this.baseUrl}/paiements/${paiementId}/valider-raf`,
            {
                method: 'POST',
                headers: {
                    'Authorization': `Bearer ${this.token}`,
                    'Content-Type': 'application/json'
                },
                body: JSON.stringify({ commentaire })
            }
        );
        return response.json();
    }

    async executer(paiementId) {
        const response = await fetch(
            `${this.baseUrl}/paiements/${paiementId}/executer`,
            {
                method: 'POST',
                headers: { 'Authorization': `Bearer ${this.token}` }
            }
        );
        return response.json();
    }
}

// Usage
const api = new PaiementsAPI(token);

// List payments for a cycle
const paiements = await api.getPaiements('770e8400-...');
console.log(`${paiements['hydra:totalItems']} payments`);

// Complete workflow
await api.soumettre('880e8400-...');
await api.validerRaf('880e8400-...', 'Compliant');
await api.validerCoord('880e8400-...', 'Approved');
const result = await api.executer('880e8400-...');
console.log(result.success ? 'Success' : 'Failure');

Python

import requests

class PaiementsAPI:
    def __init__(self, token):
        self.token = token
        self.base_url = 'https://sig.ucp-pch.org/api'
        self.headers = {'Authorization': f'Bearer {token}'}

    def get_paiements(self, cycle_id, **filters):
        response = requests.get(
            f'{self.base_url}/cycles/{cycle_id}/paiements',
            headers=self.headers,
            params=filters
        )
        return response.json()

    def soumettre(self, paiement_id):
        response = requests.post(
            f'{self.base_url}/paiements/{paiement_id}/soumettre',
            headers=self.headers
        )
        return response.json()

    def valider_raf(self, paiement_id, commentaire=None):
        response = requests.post(
            f'{self.base_url}/paiements/{paiement_id}/valider-raf',
            headers={**self.headers, 'Content-Type': 'application/json'},
            json={'commentaire': commentaire}
        )
        return response.json()

    def executer(self, paiement_id):
        response = requests.post(
            f'{self.base_url}/paiements/{paiement_id}/executer',
            headers=self.headers
        )
        return response.json()

# Usage
api = PaiementsAPI(token)

# Statistics by status
paiements = api.get_paiements(cycle_id)
stats = {}
for p in paiements['hydra:member']:
    statut = p['statut']
    stats[statut] = stats.get(statut, 0) + 1
print(stats)

Notes

• A beneficiary can only have one payment per cycle
• The validation workflow follows: brouillon -> en_attente -> valide_raf -> valide_coord -> execution
• Arrears (failed payments carried over) are marked with estArriere: true
• Transaction fees are automatically calculated based on the operator
• Validation history is kept for auditing