Quickstart - SandPay

Two paths depending on your style:

Stack Builder (recommended)
Manual integration

10 minutes, zero copy-paste code. Fill in your keys inside SandPay, download a pre-filled starter zip, and run ./setup.sh. Works on macOS, Linux, and Windows.

Create a SandPay account

Generate an API key

Go to /settings → API keys → Create new key. The sp_sk_test_… key is shown only once — keep the tab open to carry it into step 3 without having to retype it.

Choose your stack

Click “Open Integration guide with this key →” in the modal, or navigate manually to /integration (in the sidebar, under Dev → Integration). The Stack Builder page lists 5 backends and 4 mobile clients. Select:

One backend from: Supabase Edge Functions, Next.js API Routes, Express, Hono, FastAPI
Zero or more clients: Next.js web, Flutter, React Native, iOS native, Android native

Fill in your project-specific values (Supabase URL/anon/service-role if applicable, custom port, project name). Enable the “Include my secrets in .env” toggle if you want the zip ready to use (security note: the zip will then contain secrets in plain text — treat it like a password manager export).

Download and run

Click “Download zana-app.zip”. Unzip, then:

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

The script confirms your values (or prompts for them if you didn’t enable secret inclusion), then writes the .env files in the right places. Follow the displayed commands to deploy Supabase, start the backend, start the frontend, and start the mobile app.

First payment

From your web or mobile app, trigger a test payment:

Number: +250788123456 (default Rwanda MTN)
Amount: 25000
Reference: ORDER-TEST-001

You receive a synchronous status: SUCCESS, then the payment.completed webhook asynchronously a few seconds later with the synthesised operator raw field — it faithfully reproduces the native MTN/Orange/Moov/Airtel shape (with _simulated: true at the top level).

Testing locally with Supabase (Edge Functions)

Two modes, depending on whether you want to use Docker. The full details (and the network direction table) are in the starter’s README.md.

Option A — Full local (Docker required). supabase start runs everything on your machine, then supabase functions serve --env-file supabase/.env. ⚠️ Gotcha: an Edge Function runs inside a Docker container, so localhost refers to the container, not your machine. To reach SandPay (on the host at localhost:3800), the function must use http://host.docker.internal:3800. Clients point at local Supabase (http://127.0.0.1:54321); the SandPay webhook points at http://localhost:54321/functions/v1/sandpay-webhook. (On an Android emulator, the host is reached via 10.0.2.2, not 127.0.0.1.)
Option B — Mixed (cloud functions + local clients, no Docker). Edge Functions stay on Supabase cloud; your clients run locally. The cloud cannot reach your localhost:3800, so expose SandPay via ngrok with a reserved static domain (free, 1 domain): ngrok http 3800 --domain=your-name.ngrok-free.app, then supabase secrets set SANDPAY_BASE_URL=https://your-name.ngrok-free.app. Advantage: the URL stays the same across restarts → set the secret once. (cloudflared quick-tunnels and ngrok http without --domain rotate the URL on every restart — avoid them.) The webhook then points at the cloud function.

The starter zip is OS-aware: executable bit preserved on .sh, LF line endings on Linux/macOS and CRLF on PowerShell. The setup.sh script also auto-detects bash, zsh, or sh.

For developers who want to understand every piece, or who have an atypical infrastructure.

Create a SandPay account

Go to sandpay.dev/sign-up and create your organisation. Onboarding has 4 steps: profile, organisation, first operator, verification.

Connect an operator

At step 3 of onboarding (or later from /settings), choose an operator and country — for example Orange Côte d’Ivoire. In sandbox mode you can use test credentials: no network calls are made if you stay in simulation. See the operator guides for per-portal details.

Get your API key

From /settings/api-keys, create a key. It looks like sp_sk_test_a1b2c3d4.... Copy it immediately — the full value is shown only once.

First payment

Send your first POST /v1/payments request:

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"
  }'

Expected response:

{
  "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"
}

The scenario field is optional. Without an explicit value, SandPay applies success. To exercise failure paths, see the scenarios reference. To integrate into a real app, see Webhooks for receiving async statuses, and SDKs for per-stack examples.

Next steps

For a complete integration (full contract, statuses, commission, webhooks, recommended architecture), the canonical reference — the source of truth — is the Integration Guide.

Integration Guide

The full end-to-end contract — the canonical reference.

Configure webhooks

Receive async transaction statuses with HMAC signature verification.

All scenarios

10 simulation scenarios for testing every operator error case.

Operator guides

MTN, Orange, Moov, Airtel specifics.

Node.js SDK

@sandpay/node — full types, webhook helpers.

FAQ & integration tips

Webhook not firing locally, commission/net_amount, reconciliation — the questions you actually run into.

​Next steps

Integration Guide

Configure webhooks

All scenarios

Operator guides

Node.js SDK

FAQ & integration tips

Next steps