Sandbox Environment

The Settlra sandbox is a fully isolated test environment with realistic webhook events, simulated payout flows, and no real money movement. Use it during development and integration testing before promoting to production.

No real funds are moved in the sandbox. USDC deposits are simulated instantly and all mobile money transfers are synthetic.

Base URL

Point all sandbox requests at the dedicated sandbox base URL. Production and sandbox environments are completely separate — your production API keys will not work in sandbox and vice-versa.

bash

"color:#8b949e"># Sandbox
https://api-sandbox.settlra.com

"color:#8b949e"># Production
https://api.settlra.com

Sandbox API keys

Sandbox API keys are prefixed with pk_test_. You can generate them in the dashboard under Settings → API Keys → Sandbox. Never use production keys in sandbox requests.

bash

"color:#8b949e"># Sandbox key format
pk_test_51HxyzABCDEFGHIJ...

"color:#8b949e"># Using in a request
"color:#ff7b72">curl https://api-sandbox.settlra.com/v1/payouts \
  "color:#79c0ff">-H "Authorization: Bearer pk_test_your_sandbox_key"

javascript

"color:#ff7b72">import Settlra "color:#ff7b72">from '@settlra/node';

"color:#8b949e">// Automatically routes to sandbox base URL when key starts with pk_test_
"color:#ff7b72">const client = "color:#ff7b72">new Settlra({
  apiKey: process.env.SETTLRA_SANDBOX_KEY, "color:#8b949e">// pk_test_...
  baseURL: 'https://api-sandbox.settlra.com',
});

Test phone numbers

Use the numbers below to simulate specific payout outcomes. Any phone number not in this list will behave as a standard MTN Uganda success by default.

+256700000001mtn_ugandasuccessSettles in 1–3 minutes

+256700000002mtn_ugandasuccessDelayed success — settles after ~5 minutes

+256700000003mtn_ugandafailsAlways fails — reason: insufficient_balance

+256700000004mtn_ugandafailsAlways fails — reason: invalid_recipient

+256701000001airtel_ugandasuccessAirtel success — settles in 1–3 minutes

Simulated USDC deposits

In production you send USDC on-chain to a deposit address to fund a payout. In sandbox, deposits are credited instantly — no blockchain transaction is required.

After creating a payout in sandbox, Settlra automatically detects a simulated deposit and advances the payout through its full lifecycle, firing webhook events at each stage just as it would in production.

To test the webhook flow end-to-end in sandbox, set up a webhook endpoint before creating a payout. See the Webhooks API for details.

Realistic webhook events

The sandbox fires the same webhook event types as production in the same order, so your event handlers are validated end-to-end without touching live infrastructure.

Event	Timing (sandbox)
`payout.awaiting_funds`	Immediately after payout creation
`payout.stablecoin_received`	~2 seconds after creation
`payout.payout_initiated`	~5 seconds after creation
`payout.settled`	1–3 min (or 5 min for +256700000002)
`payout.failed`	Immediately for test failure numbers

Sandbox limits

Limit	Value
Max payout amount (USDC)	`10,000 per transaction`
Max batch size	`1,000 rows per batch`
API rate limit	`200 requests / minute`
Webhook retries	`5 attempts with exponential backoff`

Going to production

When you are ready to go live, swap the base URL and API key. No code changes are required beyond those two values.

javascript

"color:#8b949e">// Before (sandbox)
"color:#ff7b72">const client = "color:#ff7b72">new Settlra({
  apiKey: process.env.SETTLRA_SANDBOX_KEY,
  baseURL: 'https://api-sandbox.settlra.com',
});

"color:#8b949e">// After (production)
"color:#ff7b72">const client = "color:#ff7b72">new Settlra({
  apiKey: process.env.SETTLRA_LIVE_KEY, "color:#8b949e">// pk_live_...
  baseURL: 'https://api.settlra.com',
});