> ## 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.

# Retraits

> Envoyez de l'argent vers un bénéficiaire en mobile money (payout).

Toutes les routes de ce groupe nécessitent le header `Authorization: Bearer sk_...` et un scope de clé API `PAYOUT` ou `BOTH`.

## Vue d'ensemble

Un **payout** est l'inverse d'un paiement : au lieu d'encaisser un client, vous envoyez des fonds depuis votre solde marchand vers un bénéficiaire (`recipient`) désigné par son numéro mobile money.

```
Votre solde marchand (wallet par pays)
        │
        ▼
POST /payouts/initialize/  ──────────►  Transaction (flow_direction: "OUTBOUND")
        │                                        │
        │                                        ▼
        │                        GET /payouts/{payout_id}/verify/
        │                        revérifie toujours l'état réel côté
        │                        gateway si le statut est PENDING
        ▼
  bénéficiaire crédité (mobile money)
```

* [Initier un payout](/api-reference/payouts/initialize)
* [Vérifier le statut d'un payout](/api-reference/payouts/verify)

Pour l'historique, les filtres et l'export, voir [Transactions](/api-reference/transactions) — un payout produit une `Transaction` classique avec `flow_direction: "OUTBOUND"` et `transaction_type: "RETRAIT"`.

<Warning>
  **Whitelist IP obligatoire.** Contrairement à toutes les autres routes de cette documentation, `POST /payouts/initialize/` exige que l'IP de votre serveur soit whitelistée pour votre marchand **quand vous appelez avec une clé API**. Sans IP whitelistée, la requête échoue avec `403 ip_not_whitelisted`, même si votre clé API est valide et correctement scopée. Ce prérequis ne s'applique pas à un appel authentifié depuis le tableau de bord (JWT dashboard, pas d'IP serveur fixe à whitelister de la même façon). La whitelist elle-même se gère depuis votre tableau de bord ou l'API de gestion du marchand.
</Warning>

## Devise et pays : strict, pas de conversion automatique

Contrairement à l'encaissement (payin), où un mismatch entre `currency` et `country` est désormais auto-converti au taux de change courant, un payout **rejette** ce mismatch (`currency_country_mismatch`, `422`). Fournissez toujours une devise cohérente avec le pays du bénéficiaire (ex. `XOF` + `BJ`, `XAF` + `CM`).

## Cycle de vie d'un payout

| Statut    | Signification                                     |
| --------- | ------------------------------------------------- |
| `PENDING` | Payout initié, en attente de confirmation gateway |
| `SUCCESS` | Bénéficiaire crédité                              |
| `FAILED`  | Payout refusé ou échoué côté gateway/réseau       |

<Note>
  Un payout ne peut pas être relancé via [`/payments/{payment_id}/retry/`](/api-reference/payments/retry) — cet endpoint est réservé aux paiements entrants (`flow_direction: "INBOUND"`). Pour un payout échoué, initiez une nouvelle requête `POST /payouts/initialize/` avec une nouvelle `Idempotency-Key`.
</Note>