UC-02 — Recharge Mobile Money

Acteur : Porteur de carte (libre-service) ou agent But : Créditer une carte via un paiement Mobile Money (FedaPay)

Trigger

Un porteur souhaite recharger sa carte depuis son téléphone via Mobile Money.

Préconditions

• La carte est active
• Le fournisseur de paiement est configuré
• Le porteur connaît sa carte et son numéro Mobile Money

Postconditions

• Une session de paiement est créée (pending)
• Après confirmation du fournisseur, la carte est créditée (credit_mobile_money)

Endpoints

1. Initier la recharge

POST /api/v1/transactions/recharge
Content-Type: application/json
Idempotency-Key: <uuid-v4>

{
  "card_id": "uuid-carte",
  "amount_cents": 2000,
  "method": "mobile_money",
  "customer_phone": "+22890123456",
  "payment_provider": "fedapay"
}

customer_phone est requis pour mobile_money.

2. Callback fournisseur (webhook)

POST /api/v1/payments/callback
X-Provider-Name: fedapay
<corps brut signé>

3. Suivre le statut (polling)

GET /api/v1/payments/sessions/{session_id}

Flow

sequenceDiagram
    participant Porteur
    participant App
    participant API
    participant Provider as FedaPay
    participant DB

    Porteur->>App: "Recharger 2000 F"
    App->>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-->>App: {payment_url, session_id, provider_tx_id}
    App->>Porteur: Redirection vers la page de paiement

    Porteur->>Provider: Confirme le paiement
    Provider->>API: POST /payments/callback (signé)
    API->>API: Vérifie signature HMAC
    API->>DB: UPDATE session → completed
    API->>DB: Crédit carte (idempotent)
    API-->>Provider: {"status": "processed"}

    loop Polling
        App->>API: GET /payments/sessions/{id}
        API-->>App: {status: "successful"}
    end
    App->>Porteur: "Recharge réussie"

Réponse (initiation)

{
  "payment_url": "https://pay.fedapay.com/...",
  "session_id": "uuid",
  "provider_tx_id": null
}

Réponse (statut)

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

Permissions

Permission	Description
card.recharge.mobile_money	Recharger via Mobile Money

Erreurs

error_code	Description
Validation	customer_phone manquant, montant invalide
NotFound	Carte ou session introuvable
Internal	Fournisseur non configuré

Voir Paiements et Transaction — Recharge.