Paiements

Base URL : /api/v1/payments

Gestion des paiements Mobile Money (FedaPay). Un paiement est initié via Recharge Mobile Money puis confirmé de façon asynchrone par le fournisseur.

---

Flux de paiement

sequenceDiagram
    participant Client
    participant API
    participant Provider as FedaPay
    participant DB

    Client->>API: POST /transactions/recharge {method: mobile_money}
    API->>DB: INSERT payment_sessions (pending)
    API->>Provider: send_payment
    Provider-->>API: payment_url + provider_tx_id
    API-->>Client: {payment_url, session_id, provider_tx_id}

    Provider->>API: POST /payments/callback (webhook signé)
    API->>API: Vérifie signature HMAC
    API->>DB: Crédit carte (idempotent)
    API-->>Provider: {"status": "processed"}

Initiation

Il n'existe pas d'endpoint /initiate. L'initiation se fait via POST /transactions/recharge avec method: "mobile_money".

---

POST /payments/callback

Webhook appelé par le fournisseur de paiement. Endpoint public, sans authentification.

En-têtes

En-tête	Description
X-Provider-Name	Nom du fournisseur (défaut : fedapay)
En-tête de signature	Vérifié par le fournisseur (ex: HMAC-SHA256)

Corps

Le corps est brut (bytes) — c'est le payload signé du fournisseur, pas de structure JSON imposée côté Caffette.

Réponse (200)

{ "status": "processed" }

Les événements non terminaux (pending/unknown) renvoient :

{ "status": "ignored" }

Comportement

1. Validation de la signature via process_webhook (échec → 400 : "Invalid webhook signature" ou "Webhook validation failed: ...").
2. Recherche de la session par provider_tx_id (sinon 404).
3. Si le statut est terminal, mise à jour de la session :
   • Successful → completed
   • Failed → failed
   • Cancelled → cancelled
   • Expired → expired
4. Si Successful, ouverture d'une transaction PostgreSQL et application d'un CreditMobileMoney avec la clé d'idempotence payment_session_{session_id}.

Erreurs

Code	Description
400	Signature invalide
404	Session de paiement introuvable
500	Fournisseur de paiement non configuré ("Payment system is not configured")

---

GET /payments/sessions/{id}

Interroge le statut d'une session de paiement (authentifié).

Permissions : aucune vérification granulaire (authentification + contexte tenant requis)

Réponse (200)

{
  "id": "uuid",
  "status": "successful",
  "amount_cents": 2000,
  "payment_url": "https://pay.fedapay.com/...",
  "created_at": "2025-01-15T10:00:00Z"
}

Valeurs de status

Statut	Signification
pending	En attente de confirmation
successful	Paiement réussi, carte créditée
failed	Paiement échoué
cancelled	Paiement annulé
expired	Session expirée
refunded	Remboursé
unknown	Statut inconnu

status: "successful"

Le statut exposé est "successful" (et non "completed"), même si la ligne payment_sessions.status en base vaut "completed" après traitement.

Erreurs

Code	Description
404	Session de paiement introuvable

---

Fournisseurs

Fournisseur	provider	Webhook
FedaPay	fedapay (défaut)	Signature vérifiée
PayGate	paygate	URL-based

Le fournisseur est sélectionné à l'initiation via le champ payment_provider de POST /transactions/recharge.

---

Voir aussi

• Transactions — initiation de la recharge
• Statistiques — suivi des recharges