Payment Export

Exports of a transfer's payments to the payment operator (ST file) or to Excel, and tracking of their transmission. The operator's return file (CT) is processed by reconciliation.

Endpoints

All /api/export-paiements routes require the transferts.paiements_view permission and check that the transfer is within the user's scope (403 otherwise).

Endpoint	Method	Description
/api/export-paiements/generate-st/{cycleId}	POST	Generates the operator's ST file (protected ZIP archive)
/api/export-paiements/generate/{cycleId}	POST	Directly downloads an Excel file of the payments
/api/export-paiements	GET	Export history (cycle, limit 50 by default, offset)
/api/export-paiements/{id}	GET	Export details
/api/export-paiements/download/{id}	GET	Downloads an export's archive
/api/export-paiements/{id}/marquer-envoye	POST	Marks the export as sent to the operator
/api/export-paiements/{id}/confirmer	POST	Marks the export as confirmed by the operator
/api/export/paiements	GET	Payment data as JSON for report exports

Both generation routes accept the same filters in the JSON body: region, secteur, localite (UUID) and statut. With no matching payment: 400 Aucun paiement trouvé avec ces filtres.

---

POST /api/export-paiements/generate-st/{cycleId}

{ "region": "<uuid>", "statut": "en_attente" }

The SIG produces a password-protected ZIP archive. It contains the ST file plus a summary Excel and PDF. Exported payments in en_attente move to en_cours, and the transfer moves to en_cours if it is not finished.

{
  "success": true,
  "data": {
    "id": "…",
    "nomFichier": "20260715_143000_ST_AGENCE.zip",
    "motDePasse": "…",
    "hashSha256": "…",
    "nombreBeneficiaires": 1200,
    "montantTotal": 18000000,
    "dateGeneration": "2026-07-15T14:30:00+00:00"
  }
}

The archive password is returned in this response: send it to the operator through a different channel from the file.

ST format

The ST file is fixed-width, one line per beneficiary:

Field	Width	Content
Indicator	2	ST
Agency name	10	Padded with spaces
Payment system	10	MM
Transfer order identifier	50	Unique per transfer
Download identifier	10	Unique per beneficiary, padded with zeros
Date	8	DDMMYYYY
Value date	8	DDMMYYYY
Amount	10	No decimals, padded with zeros
Phone	24	Padded with spaces
Beneficiary name	50	Padded with spaces

---

POST /api/export-paiements/generate/{cycleId}

Directly returns a paiements_<code>_<timestamp>.xlsx file (no JSON).

---

Tracking an export

POST /api/export-paiements/{id}/marquer-envoye
POST /api/export-paiements/{id}/confirmer

Optional body: { "commentaire": "…" }. Confirmation deletes the archive from the server.

---

Operator export workflow

┌────────────────────┐
│ 1. Valider le      │
│    transfert       │
└─────────┬──────────┘
          ▼
┌────────────────────┐
│ 2. Générer le ST   │
└─────────┬──────────┘
          ▼
┌────────────────────┐
│ 3. Transmettre a   │
│    l'operateur     │
└─────────┬──────────┘
          ▼
┌────────────────────┐
│ 4. Recevoir le     │
│    fichier CT      │
└─────────┬──────────┘
          ▼
┌────────────────────┐
│ 5. Réconciliation  │
└────────────────────┘

---

Example

curl -X POST "https://sig.example.com/api/export-paiements/generate-st/<cycleId>" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"statut": "en_attente"}'

curl "https://sig.example.com/api/export-paiements/download/<exportId>" \
  -H "Authorization: Bearer TOKEN" \
  -o export_st.zip

Error codes

HTTP	Case
400	No payment matches the filters
401	Not authenticated
403	Missing permission or transfer outside scope
404	Transfer, export or file not found
500	Archive creation failed