Sandbox vs Production

Settlra provides two fully separate environments. Always develop and test against the sandbox before switching to production.

Environment comparison

Feature	Sandbox	Production
Base URL	`https://api-sandbox.settlra.com/v1`	`https://api.settlra.com/v1`
API key prefix	`sk_sandbox_`	`sk_live_`
Real money	No	Yes
Real USDC deposit	Auto-simulated	Required on-chain
Real mobile money	No — simulated	Yes — real transfers
KYC required	No	Yes (TIER_1 minimum)
Compliance screening	Mocked	Full AML + sanctions
Rate limits	Relaxed (500 req/min)	Standard (100 req/min)

Sandbox behavior

In the sandbox, all payouts succeed automatically. There is no need to send real USDC — after you create a payout, the sandbox simulates a deposit confirmation within a few seconds and marks the payout as SETTLED.

Sandbox webhooks fire to your configured endpoint the same way production webhooks do, making it easy to test your event handling end-to-end.

Test phone numbers

Use these phone numbers in sandbox to test different payout outcomes:

Phone number	Network	Sandbox behavior
`+256700000001`	MTN_UG	Always succeeds — settled in ~3s
`+256700000002`	MTN_UG	Fails with PROVIDER_ERROR after 5s
`+256700000003`	MTN_UG	Triggers compliance hold
`+256752000001`	AIRTEL_UG	Always succeeds — settled in ~3s
`+254700000001`	MPESA_KE	Always succeeds — settled in ~5s
`+254700000002`	MPESA_KE	Fails with INVALID_RECIPIENT

Switching to production

Before going live, complete these steps:

Complete KYC verification in the dashboard (required for TIER_1 access at minimum).
Generate a sk_live_ API key from the dashboard.
Update your base URL and API key environment variables.
Register your webhook endpoint (production endpoint must use HTTPS).
Test with a small live amount before scaling up.

bash

"color:#8b949e"># Sandbox
"color:#ff7b72">export SETTLRA_API_KEY="sk_sandbox_your_sandbox_key"
"color:#ff7b72">export SETTLRA_BASE_URL="https://api-sandbox.settlra.com/v1"

"color:#8b949e"># Production
"color:#ff7b72">export SETTLRA_API_KEY="sk_live_your_production_key"
"color:#ff7b72">export SETTLRA_BASE_URL="https://api.settlra.com/v1"

Configuring your client for both environments

settlra-client.jsjavascript

"color:#ff7b72">const SETTLRA_BASE_URL = process.env.NODE_ENV === 'production'
  ? 'https://api.settlra.com/v1'
  : 'https://api-sandbox.settlra.com/v1';

"color:#ff7b72">export "color:#ff7b72">async "color:#ff7b72">function settlraRequest(path, options = {}) {
  "color:#ff7b72">const response = "color:#ff7b72">await fetch(`${SETTLRA_BASE_URL}${path}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${process.env.SETTLRA_API_KEY}`,
      'Content-Type': 'application/json',
      ...options.headers,
    },
  });

  "color:#ff7b72">if (!response.ok) {
    "color:#ff7b72">const error = "color:#ff7b72">await response.json();
    "color:#ff7b72">throw "color:#ff7b72">new Error(`Settlra API error: ${error.error} — ${error.message}`);
  }

  "color:#ff7b72">return response.json();
}