UC-01 — Recharge en espèces

Acteur : Caissier But : Créditer le solde d'une carte via un paiement en espèces

Trigger

Un porteur se présente à la buvette avec du cash pour recharger sa carte.

Préconditions

• Le caissier possède la permission card.recharge.cash
• Une session de caisse est ouverte sur le point de vente
• La carte est active

Postconditions

• Le solde de la carte est crédité
• Une transaction credit_cash est enregistrée (idempotente)
• Un événement transaction.recharge_completed est émis via l'outbox

Endpoints

1. Ouvrir la session de caisse

POST /api/v1/admin/org/points-of-sale/{pos_id}/registers/open
Content-Type: application/json

{
  "opening_balance_cents": 5000,
  "notes": "Ouverture matinale"
}

2. Recharge

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

{
  "card_id": "uuid-carte",
  "amount_cents": 5000,
  "method": "cash",
  "register_id": "uuid-caisse",
  "point_of_sale_id": "uuid-pos",
  "site_id": "uuid-site"
}

Flow

sequenceDiagram
    participant Porteur
    participant Caissier
    participant POS
    participant API
    participant DB

    Porteur->>Caissier: "Je veux recharger 5000 F"
    Caissier->>POS: Ouvrir caisse
    POS->>API: POST /admin/org/points-of-sale/{id}/registers/open
    API->>DB: INSERT register (status: open)

    Caissier->>POS: Saisir carte + montant
    POS->>API: POST /transactions/recharge {method: cash}
    Note over POS,API: Idempotency-Key: uuid
    API->>DB: BEGIN
    API->>DB: Vérifie carte active + idempotence
    API->>DB: INSERT card_transactions (credit_cash)
    API->>DB: UPDATE cards.balance_cents
    API->>DB: COMMIT
    API->>API: Emit RechargeCompleted (outbox)
    API-->>POS: {transaction, new_balance_cents}
    POS->>Caissier: "Nouveau solde : 6500 F"

Exemple de réponse

{
  "transaction": {
    "id": "uuid",
    "card_id": "uuid",
    "type": "credit_cash",
    "amount_cents": 5000,
    "balance_before_cents": 1500,
    "balance_after_cents": 6500,
    "amount_formatted": "5 000 FCFA",
    "balance_after_formatted": "6 500 FCFA",
    "currency": "XOF",
    "created_at": "2025-06-01T10:30:00Z"
  },
  "new_balance_cents": 6500,
  "new_balance": 6500,
  "new_balance_formatted": "6 500 FCFA",
  "currency": "XOF"
}

Idempotence

Le POS génère un UUIDv4 par recharge. En cas de timeout, renvoyer la même requête avec la même clé retourne la transaction existante sans double-crédit.

Permissions

Permission	Description
card.recharge.cash	Recharger une carte en espèces
register.open	Ouvrir une session de caisse

Erreurs

Format : { "error_code": "...", "message": "..." }

error_code	Description
Validation	Montant ≤ 0 ou > 1 000 000 FCFA
NotFound	Carte introuvable
Forbidden	Permission insuffisante
Internal	Erreur serveur

Voir Transaction — Recharge pour le détail complet.