> ## Documentation Index
> Fetch the complete documentation index at: https://docs.saspay.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Wallet

> Consultez vos soldes par pays, enregistrez des méthodes de retrait, demandez un retrait et transférez des fonds entre pays.

Toutes les routes nécessitent votre clé API secrète (`Authorization: Bearer sk_...`) ou une session dashboard. Voir [Authentification](/api-reference/introduction#authentification).

## Un wallet par (marchand, pays)

Contrairement à une approche par devise, SasPay tient un solde distinct pour **chaque pays** où vous encaissez — jamais un solde global par devise. C'est un choix structurant : plusieurs pays partagent parfois la même devise (le XOF pour le Bénin, le Togo, la Côte d'Ivoire, le Sénégal...), et confondre les deux masquerait dans quel pays l'argent se trouve réellement.

```
Votre marchand
│
├── Wallet Bénin (XOF)   ── available_amount, pending_amount, is_frozen
├── Wallet Sénégal (XOF) ── un solde distinct, même devise
└── Wallet Cameroun (XAF)
```

Un wallet est créé automatiquement dès qu'un mouvement l'exige (premier encaissement dans ce pays, par exemple) — il n'y a pas de création manuelle.

## Soldes

Lecture seule stricte : aucune écriture n'est possible côté marchand, le solde ne bouge que via les mouvements internes de la plateforme (encaissement, retrait, ajustement admin...).

* [Lister les soldes](/api-reference/wallet/balances-list)
* [Récupérer un solde](/api-reference/wallet/balances-get)

<Note>
  Pas de filtre `?country=` disponible sur la liste — récupérez tous vos soldes et filtrez côté client.
</Note>

Le champ `is_frozen` mérite attention : quand il vaut `true`, les **entrées restent acceptées** (vos encaissements continuent d'être crédités) mais toutes les **sorties sont bloquées** (retrait, transfert sortant). Un gel est toujours décidé côté plateforme, jamais déclenché par le marchand.

## Relevé de mouvements (ledger)

Journal append-only de tous les mouvements ayant affecté un de vos soldes — encaissement, retrait, frais, ajustement, remboursement, transfert entrant/sortant. Chaque ligne est immuable et porte le solde avant/après pour reconstituer l'historique sans ambiguïté.

* [Lister les mouvements](/api-reference/wallet/ledger-list)
* [Récupérer un mouvement](/api-reference/wallet/ledger-get)

<Note>
  Pas de filtre `?type=` ni `?country=` disponible sur cette vue — récupérez et filtrez côté client.
</Note>

## Méthodes de retrait

Une méthode de retrait (mobile money ou virement bancaire) doit être enregistrée avant de pouvoir demander un retrait.

* [Lister les méthodes de retrait](/api-reference/wallet/payout-methods-list)
* [Enregistrer une méthode de retrait](/api-reference/wallet/payout-methods-create)
* [Récupérer une méthode de retrait](/api-reference/wallet/payout-methods-get)
* [Modifier une méthode de retrait](/api-reference/wallet/payout-methods-update)
* [Supprimer une méthode de retrait](/api-reference/wallet/payout-methods-delete)

<Warning>
  Aucune validation croisée serveur ne force les champs pertinents selon `type` : rien n'empêche aujourd'hui de créer une méthode `MOBILE_MONEY` sans `network`/`phone_number`, ou `BANK_TRANSFER` sans coordonnées bancaires. Validez ces champs vous-même côté intégration avant de les envoyer.
</Warning>

Toute méthode nouvellement créée a `is_verified: false` — un administrateur SasPay doit la vérifier avant qu'elle puisse servir à un retrait. Ce délai de vérification est volontaire : c'est le point de contrôle contre le détournement d'un retrait vers des coordonnées non validées.

## Retraits

Demandez un retrait de votre solde disponible vers une méthode de retrait déjà vérifiée.

* [Demander un retrait](/api-reference/wallet/settlements-create)
* [Lister les retraits](/api-reference/wallet/settlements-list)
* [Récupérer un retrait](/api-reference/wallet/settlements-get)
* [Annuler un retrait en attente](/api-reference/wallet/settlements-cancel)

<Warning>
  Un retrait fait sortir de l'argent réel de la plateforme — l'endpoint de création exige un header `Idempotency-Key`. Sans lui, deux requêtes identiques (double-clic, retry réseau) créeraient deux retraits distincts, débitant chacun votre solde séparément. Voir [Idempotence](/api-reference/introduction#idempotence).
</Warning>

Les frais (`client_fee`, `gateway_fee`, `platform_fee`) sont calculés côté serveur selon votre configuration tarifaire — jamais saisis par vous. Le `fee_charge_mode` détermine si les frais sont déduits du montant retiré (`DEDUCTED`) ou facturés séparément.

## Transferts interwallet

Déplacez des fonds entre deux de vos wallets (pays différents), avec conversion de devise automatique si nécessaire.

* [Créer un transfert](/api-reference/wallet/transfers-create)
* [Lister les transferts](/api-reference/wallet/transfers-list)
* [Récupérer un transfert](/api-reference/wallet/transfers-get)

<Note>
  Un seul transfert `PENDING` est autorisé à la fois par marchand. Selon votre configuration, le transfert peut soit passer directement à `COMPLETED` dans la même requête (auto-approbation activée par un administrateur), soit rester `PENDING` jusqu'à validation manuelle.
</Note>

Comme pour un retrait, l'endpoint de création exige un header `Idempotency-Key` — un transfert reste un mouvement d'argent, même s'il ne quitte pas la plateforme.

## Taux de change

Les taux appliqués aux transferts interwallet lors d'une conversion de devise.

* [Lister les taux de change](/api-reference/wallet/exchange-rates-list)

<Note>
  Pas de filtre par paire de devises — listez tout et filtrez côté client.
</Note>