# Gouaklô V4.2.3 — Finance & Paiements

Date : 06 septembre 2026

## Objectif
Renforcer le domaine financier sans simuler de paiement réel. Le serveur reste la seule source de vérité pour les montants, commissions, wallets, remboursements et rapprochements.

## Livré
- `database/005_v423_finance.sql`
  - ledger financier append-only
  - remboursements et lignes de remboursement
  - rapprochement financier
  - unicité provider/reference et idempotence paiement
  - contraintes financières complémentaires
- API finance
  - `GET /finance/summary`
  - `GET /finance/ledger`
- API remboursement
  - `POST /orders/{id}/refunds` : demande client
  - `GET /orders/{id}/refunds` : suivi client
  - `GET /admin/refunds` : supervision admin
  - `POST /admin/refunds/{id}/approve` : validation admin
  - `POST /payments/refund-webhook` : confirmation signée du provider
- Réconciliation
  - `POST /admin/reconciliation/runs`
  - `GET /admin/reconciliation/runs`
  - `GET /admin/reconciliation/runs/{id}`

## Flux remboursement
1. Client demande un remboursement.
2. Le serveur vérifie que la commande est payée et que le cumul demandé ne dépasse pas le paiement.
3. L'administrateur approuve la demande.
4. Le fournisseur de paiement exécute le remboursement réel.
5. Le fournisseur appelle le webhook signé `refund.succeeded`.
6. Le serveur vérifie event_id, paiement, montant et devise.
7. Le serveur débite le wallet vendeur du net et journalise la reprise de commission.
8. Une demande entièrement remboursée fait passer la commande à `refunded`.

Aucune étape ne considère une simple réponse frontend comme preuve de paiement ou de remboursement.

## Réconciliation
La création d'une session de rapprochement initialise un état `open`. Elle ne prétend pas connaître les encaissements du fournisseur. Les montants reçus doivent être alimentés par une intégration fournisseur réelle ou par un import contrôlé avant clôture.

## Paiement réel
La V4.2.3 conserve l'abstraction provider. Le prestataire réel, ses identifiants, son SDK/redirect et son contrat webhook restent à configurer. Aucun nom de prestataire ou succès de transaction n'est inventé.

## Tests obligatoires avant production
- double webhook paiement
- double webhook remboursement
- remboursement supérieur au paiement
- remboursement partiel répété
- remboursement après expiration/annulation
- concurrence sur wallet vendeur
- concurrence sur payout
- montant/devise/provider_reference incohérents
- restauration PostgreSQL
- rapprochement avec export réel du provider