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

# Paiements

> Encaissez un client en mobile money ou carte, via softpay (push direct) ou checkout hébergé (page à rediriger).

Toutes les routes de ce groupe nécessitent le header `Authorization: Bearer sk_...` et un scope de clé API `PAYIN` ou `BOTH` (voir [Format des réponses](/api-reference/introduction#format-des-r%C3%A9ponses) pour l'enveloppe de réponse et [Idempotence](/api-reference/introduction#id%C3%A9potence) pour le header `Idempotency-Key`).

## Vue d'ensemble

SasPay propose deux façons d'encaisser, selon que vous connaissez déjà le réseau et le numéro du client ou non :

```
                    ┌─────────────────────────────┐
                    │   Vous connaissez déjà le    │
                    │   réseau + numéro du client  │
                    └───────────────┬───────────────┘
                       oui ─────────┼───────── non
                         │                       │
                         ▼                       ▼
              POST /payments/softpay/   POST /checkout-sessions/
              Push direct sur le        Génère une page hébergée
              téléphone du client       (checkout_url) à rediriger
              — pas de redirection      le client dessus
                         │                       │
                         └───────────┬───────────┘
                                     ▼
                     Transaction créée (PENDING → SUCCESS/FAILED)
                                     │
                                     ▼
                 GET /payments/{payment_id}/verify/  ← revérifie
                 toujours l'état réel côté gateway, jamais confiance
                 dans un statut mémorisé
```

<Info>
  **Softpay vs checkout hébergé** — le softpay pousse directement une demande de paiement (USSD/notification) sur le téléphone du client à partir du réseau et du numéro que vous fournissez : idéal quand votre propre interface a déjà collecté ces informations. Le checkout hébergé génère une page de paiement SasPay (`checkout_url`) où c'est le client qui choisit son réseau et saisit son numéro — idéal pour un lien envoyé par email/SMS ou un bouton "Payer" qui redirige vers nous.
</Info>

## Softpay (push direct)

* [Initier un paiement softpay](/api-reference/payments/softpay)
* [Confirmer par OTP](/api-reference/payments/confirm-otp)
* [Relancer un paiement échoué](/api-reference/payments/retry)

## Checkout hébergé

* [Créer une session de checkout](/api-reference/payments/checkout-create)
* [Lister ses sessions de checkout](/api-reference/payments/checkout-list)
* [Détail d'une session](/api-reference/payments/checkout-get)
* [Annuler une session](/api-reference/payments/checkout-cancel)

## Commun aux deux

* [Vérifier le statut d'un paiement](/api-reference/payments/verify)

Pour l'historique complet, les filtres, l'export CSV et la facture PDF, voir [Transactions](/api-reference/transactions) — softpay et checkout hébergé produisent tous les deux une `Transaction` classique (`flow_direction: "INBOUND"`).

## Confirmation OTP

Certains réseaux (par exemple Wizall au Sénégal ou Coris au Bénin) exigent une deuxième étape : après le push initial, le client reçoit un code qu'il doit vous communiquer, à transmettre ensuite via [`POST /payments/{payment_id}/confirm-otp/`](/api-reference/payments/confirm-otp). La plupart des réseaux mobile money n'en ont pas besoin — le client valide directement sur son téléphone.

<Warning>
  `POST /checkout-sessions/` n'exige pas de header `Idempotency-Key` (dette technique connue) — un double-clic côté client ou un retry réseau non protégé peut créer deux sessions de checkout distinctes. Softpay, retry et payout, eux, exigent bien cette clé.
</Warning>

## Cycle de vie d'un paiement

| Statut      | Signification                                                                              |
| ----------- | ------------------------------------------------------------------------------------------ |
| `PENDING`   | Paiement poussé, en attente de la validation du client ou du gateway                       |
| `SUCCESS`   | Paiement confirmé et crédité                                                               |
| `FAILED`    | Paiement refusé ou échoué côté gateway/réseau                                              |
| `CANCELLED` | Jamais atteint sur ce flux actuellement (voir [Transactions](/api-reference/transactions)) |

Un paiement `FAILED` peut être rejoué sans créer de nouvelle transaction via [`POST /payments/{payment_id}/retry/`](/api-reference/payments/retry).