UC-07 — Correction de solde

Acteur : Superviseur / Gestionnaire But : Corriger manuellement le solde d'une carte

Trigger

Un incident nécessite une correction manuelle (erreur de caisse, annulation, ajustement).

Préconditions

• Permission card.correction
• Pour un débit rendant le solde négatif : card.balance.manual_adjust requis

Postconditions

• Le solde est ajusté du montant
• Une transaction correction est enregistrée avec la raison

Endpoint

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

{
  "card_id": "uuid-carte",
  "amount_cents": 2000,
  "direction": "debit",
  "reason": "Annulation achat erroné du 2025-06-01"
}

Pour un crédit :

{
  "card_id": "uuid-carte",
  "amount_cents": 5000,
  "direction": "credit",
  "reason": "Remboursement suite à réclamation"
}

amount_cents est positif

Le montant est absolu (> 0). Le sens est donné par direction ("credit" ou "debit"). L'omission de direction (mode hérité par signe) est dépréciée.

Flow

sequenceDiagram
    participant Superviseur
    participant Dashboard
    participant API
    participant DB

    Superviseur->>Dashboard: "Corriger le solde de la carte"
    Dashboard->>API: POST /transactions/correction
    API->>DB: BEGIN
    API->>DB: INSERT card_transactions (correction)
    API->>DB: UPDATE cards.balance_cents
    API->>DB: COMMIT
    API-->>Dashboard: {transaction, new_balance}
    Dashboard->>Superviseur: "Correction appliquée ✓"

Exemple de réponse

{
  "transaction": {
    "id": "uuid",
    "card_id": "uuid",
    "type": "correction",
    "amount_cents": 2000,
    "balance_before_cents": 5000,
    "balance_after_cents": 3000,
    "currency": "XOF",
    "created_at": "2025-06-02T09:00:00Z"
  },
  "new_balance_cents": 3000,
  "new_balance": 3000,
  "new_balance_formatted": "3 000 FCFA",
  "currency": "XOF"
}

Permissions

Permission	Description
card.correction	Effectuer une correction de solde
card.balance.manual_adjust	Autoriser un solde négatif (préscolaire)

Erreurs

error_code	Description
Validation	amount_cents ≤ 0, direction invalide, reason manquant
Forbidden	Solde négatif sans card.balance.manual_adjust
NotFound	Carte introuvable

Voir Transaction — Correction.