Démarrage rapide

Deux chemins selon votre style :

Stack Builder (recommended)
Manual integration

10 minutes, zero copy-paste de code. Vous remplissez vos clés dans SandPay, vous téléchargez un starter zip pré-rempli, vous lancez ./setup.sh. Marche pour macOS, Linux et Windows.

Créer un compte SandPay

Inscrivez-vous sur sandpay.dev/sign-up. L’onboarding prend ~30 secondes : email, mot de passe, premier opérateur.

Générer une clé API

Allez dans /settings → API keys → Create new key. La clé sp_sk_test_… n’est affichée qu’une seule fois — gardez l’onglet ouvert pour passer à l’étape 3 sans avoir à la recopier.

Choisir votre stack

Cliquez sur le bouton “Open Integration guide with this key →” dans la modale, ou allez manuellement à /integration (dans la sidebar, section Dev → Integration). La page Stack Builder liste 5 backends et 4 clients mobiles. Cochez :

Un backend parmi : Supabase Edge Functions, Next.js API Routes, Express, Hono, FastAPI
Zero ou plus de clients : Next.js web, Flutter, React Native, iOS native, Android native

Renseignez les valeurs spécifiques à votre projet (Supabase URL/anon/service-role si applicable, port custom, nom de projet). Activez le toggle “Include my secrets in .env” si vous voulez que le zip soit prêt à l’emploi (sécurité : le zip contient alors des secrets en clair — traitez-le comme un export de gestionnaire de mots de passe).

Télécharger et lancer

Cliquez sur “Download zana-app.zip”. Décompressez, puis :

unzip zana-app.zip
cd zana-app
./setup.sh

Le script confirme vos valeurs (ou les demande si vous n’avez pas activé l’inclusion des secrets), puis écrit les fichiers .env au bon endroit. Suivez les commandes affichées pour déployer Supabase, lancer le backend, lancer le frontend et lancer le mobile.

Premier paiement

Depuis votre app web ou mobile, lancez un paiement test :

Numéro : +250788123456 (default Rwanda MTN)
Montant : 25000
Référence : ORDER-TEST-001

Vous recevez status: SUCCESS synchrone, puis le webhook payment.completed async quelques secondes plus tard avec le champ raw opérateur synthétisé — il reproduit fidèlement la shape native MTN/Orange/Moov/Airtel (avec _simulated: true au top-level).

Tester en local avec Supabase (Edge Functions)

Deux modes, selon que vous voulez utiliser Docker ou non. Le détail complet (et le tableau des directions réseau) est dans le README.md du starter.

Option A — Full local (Docker requis). supabase start lance tout sur votre machine, puis supabase functions serve --env-file supabase/.env. ⚠️ Gotcha : une Edge Function tourne dans un conteneur Docker, donc localhost y désigne le conteneur, pas votre machine. Pour joindre SandPay (sur l’hôte en localhost:3800), la fonction doit utiliser http://host.docker.internal:3800. Les clients pointent sur le Supabase local (http://127.0.0.1:54321) ; le webhook SandPay pointe sur http://localhost:54321/functions/v1/sandpay-webhook. (Sur émulateur Android, l’hôte se joint via 10.0.2.2, pas 127.0.0.1.)
Option B — Mixte (fonctions cloud + clients locaux, sans Docker). Les Edge Functions restent sur Supabase cloud ; vos clients tournent en local. Le cloud ne peut pas joindre votre localhost:3800, donc exposez SandPay via ngrok avec un domaine statique réservé (gratuit, 1 domaine) : ngrok http 3800 --domain=votre-nom.ngrok-free.app, puis supabase secrets set SANDPAY_BASE_URL=https://votre-nom.ngrok-free.app. Avantage : l’URL ne change plus entre les redémarrages → vous posez le secret une seule fois. (Les quick-tunnels cloudflared et ngrok http sans --domain font tourner l’URL à chaque redémarrage — à éviter.) Le webhook pointe alors sur la fonction cloud.

Le starter zip est OS-aware : bit exécutable préservé sur .sh, line endings LF sur Linux/macOS et CRLF sur PowerShell. Le script setup.sh détecte aussi automatiquement bash, zsh ou sh.

Pour les devs qui veulent comprendre chaque morceau ou qui ont une infra atypique.

Créer un compte SandPay

Rendez-vous sur sandpay.dev/sign-up et créez votre organisation. L’onboarding prend 4 étapes : profil, organisation, premier opérateur, vérification.

Connecter un opérateur

À l’étape 3 de l’onboarding (ou plus tard depuis /settings), choisissez un opérateur et un pays — par exemple Orange Côte d’Ivoire. Pour le mode sandbox vous pouvez utiliser des credentials de test : aucun appel réseau n’est nécessaire si vous restez en simulation. Consultez les guides opérateurs pour les détails de chaque portail.

Récupérer votre clé API

Depuis /settings/api-keys, créez une clé. Elle ressemble à sp_sk_test_a1b2c3d4.... Copiez-la immédiatement — la valeur complète n’est affichée qu’une seule fois.

Premier paiement

Envoyez votre première requête POST /v1/payments :

curl -X POST https://api.sandpay.dev/v1/payments \
  -H "Authorization: Bearer $SANDPAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 25000,
    "currency": "FCFA",
    "operator": "orange",
    "country": "CI",
    "msisdn": "+22507123456",
    "reference": "ORDER-2026-A1",
    "scenario": "success"
  }'

Réponse attendue :

{
  "id": "TX_8K3M9F",
  "amount": 25000,
  "currency": "FCFA",
  "operator": "orange",
  "country": "CI",
  "msisdn": "+22507123456",
  "reference": "ORDER-2026-A1",
  "scenario": "success",
  "status": "SUCCESS",
  "latencyMs": 1240,
  "createdAt": "2026-05-23T10:14:02.412Z"
}

Le champ scenario est optionnel. Sans valeur explicite, SandPay applique success. Pour exercer les chemins d’échec, voyez la référence des scénarios. Pour intégrer dans une vraie app, voir Webhooks pour recevoir les statuts async, et SDKs pour les exemples par stack.

Prochaines étapes

Pour intégrer correctement (contrat complet, statuts, commission, webhooks, architecture recommandée), la référence canonique — la source de vérité — est le Integration Guide.

Integration Guide

Le contrat complet de bout en bout — la référence canonique.

Configurer les webhooks

Recevez les statuts asynchrones des transactions avec signature HMAC.

Tous les scénarios

10 scénarios de simulation pour tester chaque cas d’erreur opérateur.

Guides opérateurs

Spécificités MTN, Orange, Moov, Airtel.

SDK Node.js

@sandpay/node — types complets, helpers webhook.

FAQ & tips d'intégration

Webhook qui ne part pas en local, commission/net_amount, réconciliation — les questions qu’on se pose vraiment.

​Prochaines étapes

Integration Guide

Configurer les webhooks

Tous les scénarios

Guides opérateurs

SDK Node.js

FAQ & tips d'intégration

Prochaines étapes