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

# Vue d'ensemble

> Base URL, versionnage, rate limits

L'API SandPay est documentée par une spec **OpenAPI 3.1** versionnée dans le repo et auto-rendue par Mintlify. Chaque endpoint produit sa propre page de référence interactive (essai en direct, schémas de requête/réponse, exemples).

## Base URL

| Environnement | URL                       |
| ------------- | ------------------------- |
| Sandbox       | `https://api.sandpay.dev` |

Les clés `sp_sk_test_...` produisent des transactions simulées — aucune somme d'argent ne circule.

## Authentification

Bearer token sur chaque requête :

```http theme={null}
Authorization: Bearer sp_sk_test_a1b2c3d4...
```

Voir [Authentification](/fr/authentication) pour le détail du format de clé, de la rotation et des erreurs.

## Versionnage

L'API est versionnée dans l'URL : tous les endpoints publics vivent sous `/v1/`. Les changements compatibles (ajout de champs, ajout d'endpoints) sont déployés directement sur `/v1`. Les **breaking changes** déclenchent une nouvelle version (`/v2`) avec une période de chevauchement d'au moins 12 mois.

## Endpoints disponibles

| Méthode | Endpoint                   | Description                               |
| ------- | -------------------------- | ----------------------------------------- |
| `GET`   | `/v1/health`               | Sonde de santé (pas d'auth requise).      |
| `POST`  | `/v1/payments`             | Créer un paiement simulé.                 |
| `GET`   | `/v1/payments/{id}`        | Récupérer un paiement par son `tx_id`.    |
| `GET`   | `/v1/payments`             | Lister les paiements (cursor pagination). |
| `POST`  | `/v1/payments/{id}/refund` | Rembourser tout ou partie d'une collecte. |
| `POST`  | `/v1/disbursements`        | Payout libre (marchand → un msisdn).      |
| `GET`   | `/v1/meta`                 | Version d'API + capabilities (sans auth). |

## Raw operator response (`raw`)

Chaque ressource `Payment` (en POST, GET ou liste) inclut un champ `raw` avec la **shape native de l'opérateur** (MTN MoMo, Orange Money, Moov, Airtel). En sandbox cette shape est synthétisée pour correspondre à la vraie structure opérateur, avec `_simulated: true` au top-level. Voir [Scénarios](/fr/scenarios#raw-operator-response-raw) pour des exemples par opérateur.

## Rate limits

| Plan         | Limite par minute |
| ------------ | ----------------- |
| Trial / Free | 100 req/min       |
| Pro          | 1 000 req/min     |
| Pro Lifetime | 1 000 req/min     |
| Custom       | sur demande       |

Au-delà du seuil, l'API renvoie `429 rate_limited` avec un en-tête `Retry-After`. Voir [Erreurs](/fr/errors) pour la stratégie de retry.

## Quotas

Indépendamment du rate limit, chaque organisation a un **quota mensuel de simulations** (renouvelé le 1er du mois). Le dépassement renvoie `402 quota_exceeded`. Mettez à niveau le plan depuis `/settings/billing` pour l'augmenter.

## Spec OpenAPI

La spec brute est versionnée dans le repo : `docs-site/openapi/sandpay.yaml`. Mintlify l'utilise pour générer automatiquement les pages détaillées de chaque endpoint dans la sidebar de cette section.

## Voir aussi

* [Démarrage rapide](/fr/quickstart) — premier appel
* [Erreurs](/fr/errors) — codes HTTP et stratégie de retry
* [SDK Node](/fr/sdks/node) — client TypeScript officiel