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

# Démarrage rapide

> Premier paiement en 10 minutes

Deux chemins selon votre style :

<Tabs>
  <Tab title="Stack Builder (recommended)">
    <Note>
      **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.
    </Note>

    <Steps>
      <Step title="Créer un compte SandPay">
        Inscrivez-vous sur [sandpay.dev/sign-up](https://sandpay.dev/sign-up). L'onboarding prend \~30 secondes : email, mot de passe, premier opérateur.
      </Step>

      <Step title="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.
      </Step>

      <Step title="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).
      </Step>

      <Step title="Télécharger et lancer">
        Cliquez sur **"Download zana-app.zip"**. Décompressez, puis :

        <CodeGroup>
          ```bash macOS / Linux theme={null}
          unzip zana-app.zip
          cd zana-app
          ./setup.sh
          ```

          ```powershell Windows theme={null}
          Expand-Archive zana-app.zip
          cd zana-app
          .\setup.ps1
          ```
        </CodeGroup>

        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.
      </Step>

      <Step title="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).
      </Step>
    </Steps>

    <Accordion title="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.
    </Accordion>

    <Tip>
      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`.
    </Tip>
  </Tab>

  <Tab title="Manual integration">
    Pour les devs qui veulent comprendre chaque morceau ou qui ont une infra atypique.

    <Steps>
      <Step title="Créer un compte SandPay">
        Rendez-vous sur [sandpay.dev/sign-up](https://sandpay.dev/sign-up) et créez votre organisation. L'onboarding prend 4 étapes : profil, organisation, premier opérateur, vérification.
      </Step>

      <Step title="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](/fr/operators/mtn) pour les détails de chaque portail.
      </Step>

      <Step title="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.
      </Step>

      <Step title="Premier paiement">
        Envoyez votre première requête `POST /v1/payments` :

        <CodeGroup>
          ```bash curl theme={null}
          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"
            }'
          ```

          ```ts Node SDK theme={null}
          import { SandPay } from "@drwintech/sandpay";

          const sp = new SandPay({ apiKey: process.env.SANDPAY_API_KEY! });

          const tx = await sp.payments.create({
            amount: 25000,
            currency: "FCFA",
            operator: "orange",
            country: "CI",
            msisdn: "+22507123456",
            reference: "ORDER-2026-A1",
            scenario: "success",
          });

          console.log(tx.id, tx.status);
          ```
        </CodeGroup>

        Réponse attendue :

        ```json theme={null}
        {
          "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"
        }
        ```
      </Step>
    </Steps>

    <Note>
      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](/fr/scenarios). Pour intégrer dans une vraie app, voir [Webhooks](/fr/webhooks) pour recevoir les statuts async, et [SDKs](/fr/sdks/node) pour les exemples par stack.
    </Note>
  </Tab>
</Tabs>

## Prochaines étapes

<Tip>
  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**](/fr/integration-guide).
</Tip>

<CardGroup cols={2}>
  <Card title="Integration Guide" icon="book" href="/integration-guide">
    Le contrat complet de bout en bout — la référence canonique.
  </Card>

  <Card title="Configurer les webhooks" icon="webhook" href="/webhooks">
    Recevez les statuts asynchrones des transactions avec signature HMAC.
  </Card>

  <Card title="Tous les scénarios" icon="list" href="/scenarios">
    10 scénarios de simulation pour tester chaque cas d'erreur opérateur.
  </Card>

  <Card title="Guides opérateurs" icon="phone" href="/operators/mtn">
    Spécificités MTN, Orange, Moov, Airtel.
  </Card>

  <Card title="SDK Node.js" icon="code" href="/sdks/node">
    @drwintech/sandpay — types complets, helpers webhook.
  </Card>

  <Card title="FAQ & tips d'intégration" icon="circle-question" href="/integration-faq">
    Webhook qui ne part pas en local, commission/`net_amount`, réconciliation — les questions qu'on se pose vraiment.
  </Card>
</CardGroup>