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

# Référence API

> Documentation complète de l'API SasPay — encaissement, retraits, wallet, webhooks et KYC.

## Base URL

Toutes les requêtes doivent être adressées à :

```
https://api.saspay.me/api/v1
```

## Authentification

Toutes les routes marchand nécessitent votre clé API secrète, transmise dans le header `Authorization` au format Bearer :

```bash theme={null}
Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx
```

Utilisez une clé `sk_test_...` en environnement de test, `sk_live_...` en production. Retrouvez vos clés API dans votre [tableau de bord](https://app.saspay.me), section Développeur.

<Warning>
  Votre clé secrète donne accès complet à votre compte marchand (encaissement, retraits, solde). Ne l'exposez jamais côté client (navigateur, application mobile) — utilisez-la uniquement depuis votre backend.
</Warning>

## Format des réponses

Toutes les réponses de l'API partagent la même enveloppe, qu'il s'agisse d'un succès ou d'une erreur.

<CodeGroup>
  ```json Succès theme={null}
  {
    "success": true,
    "data": { },
    "code": 200
  }
  ```

  ```json Erreur theme={null}
  {
    "success": false,
    "error": {
      "message": "Solde disponible insuffisant.",
      "code": "insufficient_balance"
    },
    "code": 422
  }
  ```
</CodeGroup>

Le champ `error` prend deux formes selon le type d'erreur :

* **Erreur métier** (`{"message": "...", "code": "..."}`) — un code d'erreur stable que vous pouvez tester dans votre code, ex. `insufficient_balance`, `merchant_suspended`.
* **Erreur de validation** (`{"champ": ["message"], "autre_champ": ["message"]}`) — une entrée par champ invalide du corps de la requête.

## Codes d'erreur HTTP

| Code  | Signification                                                                                                      |
| ----- | ------------------------------------------------------------------------------------------------------------------ |
| `400` | Corps de requête invalide (champ manquant, format incorrect)                                                       |
| `401` | Clé API manquante, invalide ou expirée                                                                             |
| `403` | Ressource n'appartenant pas à votre compte, ou compte suspendu                                                     |
| `404` | Ressource introuvable                                                                                              |
| `409` | Conflit d'état (ex. `Idempotency-Key` déjà utilisée avec un autre payload, transaction déjà dans un état terminal) |
| `410` | Ressource expirée (ex. lien de paiement ou session de checkout arrivé à expiration)                                |
| `422` | Requête valide mais impossible à exécuter en l'état (ex. solde insuffisant)                                        |
| `429` | Trop de requêtes — respectez la limite de débit                                                                    |

## Idempotence

Les endpoints de création sensibles (paiement, retrait, nouvelle tentative) exigent un header `Idempotency-Key` : une valeur unique que vous générez par tentative logique d'opération (un UUID, par exemple). Si le réseau coupe et que vous rejouez la même requête avec la **même** clé, SasPay renvoie le résultat de la première tentative au lieu de créer un doublon.

```bash theme={null}
Idempotency-Key: 3fa85f64-5717-4562-b3fc-2c963f66afa6
```

Rejouer la même clé avec le **même** corps de requête renvoie la réponse exacte de la première tentative (même code HTTP, même contenu) sans rien recréer. La rejouer avec un corps **différent** renvoie `409 Conflict` — la clé est déjà associée à une autre requête. Si la première tentative est encore en cours de traitement, un rejeu concurrent renvoie aussi `409`.

<Tip>
  Générez une nouvelle `Idempotency-Key` à chaque nouvelle intention de paiement, mais réutilisez la même clé pour chaque *retry réseau* de cette même tentative.
</Tip>

## Limite de débit

Les appels authentifiés (clé API ou dashboard) sont limités à **300 requêtes par minute** par compte par défaut. Un dépassement renvoie `429 Too Many Requests`. Espacez vos appels ou mettez en cache les réponses peu volatiles (ex. liste des pays/réseaux supportés).

## Ressources

<CardGroup cols={2}>
  <Card title="Paiements" icon="credit-card" href="/api-reference/payments">
    Encaissez via checkout hébergé ou softpay
  </Card>

  <Card title="Liens de paiement" icon="link" href="/api-reference/payment-links">
    Créez des liens de paiement réutilisables
  </Card>

  <Card title="Retraits" icon="paper-plane" href="/api-reference/payouts">
    Payez un bénéficiaire en mobile money
  </Card>

  <Card title="Wallet" icon="wallet" href="/api-reference/wallet">
    Consultez et retirez votre solde
  </Card>

  <Card title="Webhooks" icon="webhook" href="/api-reference/webhooks">
    Recevez vos événements en temps réel
  </Card>

  <Card title="KYC" icon="id-card" href="/api-reference/kyc">
    Soumettez votre dossier d'identité
  </Card>
</CardGroup>