Base URL
| Environnement | URL |
|---|---|
| Sandbox | https://api.sandpay.dev |
sp_sk_test_... produisent des transactions simulées — aucune somme d’argent ne circule.
Authentification
Bearer token sur chaque requête :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 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 |
429 rate_limited avec un en-tête Retry-After. Voir Erreurs 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 renvoie402 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 — premier appel
- Erreurs — codes HTTP et stratégie de retry
- SDK Node — client TypeScript officiel