9. Mass payments

Salaries, suppliers, grouped refunds. Three steps: (1) create the batch (no money moves), (2) trigger it, (3) track its progress.

Create a batch

POST/mass-paymentsSession token

Request body

{
  "application_id": 12,
  "reference": "Salaire_Juin_2026",
  "currency": "XAF",
  "beneficiaries": [
    {
      "nom": "Bénéficiaire 1",
      "telephone": "691028372",
      "montant": 10000,
      "provider": "orange_money_cm"
    },
    {
      "nom": "Bénéficiaire 2",
      "telephone": "677895412",
      "montant": 10000,
      "provider": "mtn_momo_cm"
    }
  ]
}

Response 201 (excerpt)

{
  "success": true,
  "data": {
    "uuid": "...",
    "reference": "Salaire_Juin_2026",
    "currency": "XAF",
    "total_amount": 20000,
    "beneficiary_count": 2,
    "statut": "en_attente",
    "beneficiaries": [
      "..."
    ]
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

Trigger and track

All or nothing: a single invalid beneficiary and nothing is saved (422 with errors indexed by beneficiary).
Import from a file: POST /mass-payments/preview-csv returns a preview before creation.
POST /mass-payments/{uuid}/trigger (202) starts the run in the background, once per batch (422 if already triggered). Status: en_attente → en_cours → valide / partiellement_reussi / echoue.
Tracking: GET /mass-payments/{uuid}; list: GET /mass-payments.