8. Solde et retraits

Solde : GET /merchant/wallet (global par devise) et GET /applications/{id}/balance (par application). Détails et réponses : Marchand particulier, étape 8.

Retrait instantané

POST/withdrawalsJeton de session

Pour une entreprise, application_id est obligatoire. Même vérification préalable (POST /withdrawals/account-inquiry), mêmes corps et réponses que pour le particulier. Historique : GET /withdrawals.

Pour un virement bancaire, ajoutez destination_type: "bank" et l'application_id. L'IBAN du profil entreprise est utilisé ; consultez la section « Retirer par virement bancaire » du parcours particulier pour les conditions, exemples et erreurs.

Retrait programmé

POST/scheduled-withdrawalsJeton de session

Réservé aux entreprises : le montant est retenu au déclenchement de chaque occurrence.

Corps de la requête

{
  "application_id": 12,
  "amount": 15000,
  "destination_provider": "orange_money_cm",
  "destination_phone_number": "696246686",
  "frequency": "monthly",
  "day_of_month": 1,
  "time_of_day": "12:30",
  "starts_from": "2026-12-01",
  "currency": "XAF"
}

Réponse 201 (extrait)

{
  "success": true,
  "data": {
    "application_id": 12,
    "amount": 15000,
    "frequency": "monthly",
    "day_of_month": 1,
    "time_of_day": "12:30:00",
    "next_execution_at": "2026-12-01T12:30:00Z",
    "is_active": true,
    "status": "active",
    "currency": "XAF"
  },
  "meta": {
    "request_id": "...",
    "timestamp": "..."
  }
}

frequency : once, daily, weekly (exige day_of_week, 1 = lundi à 7 = dimanche), monthly (exige day_of_month, 1 à 31 ; ramené au dernier jour d'un mois plus court).
Statuts : active, paused, completed (fréquence once terminée), cancelled. Modifier / mettre en pause : PATCH /scheduled-withdrawals/{id}. Annuler : DELETE /scheduled-withdrawals/{id}. Historique des occurrences : GET /scheduled-withdrawals/executions.
Erreurs : 403 (compte non entreprise), 422 (données invalides).