Guides

Using the Sandbox

How to test your integration against a sandboxed environment

The sandbox provides an isolated copy of your data where you can safely test API integrations without affecting production.

Overview

• Activation creates a separate sandbox tenant with sample data (merchants, deals, payments)
• Test API keys (smca_test_*) automatically route to the sandbox
• Live API keys (smca_live_*) continue to hit your real data
• Reset wipes sandbox data and re-seeds fresh sample records
• Deactivation revokes all test keys and stops sandbox billing

Activating the Sandbox

Via the UI

1. Go to Settings → API Access
2. Find the Sandbox Environment card
3. Click Activate Sandbox
4. Copy the test API key shown (it won’t be displayed again)

Via the API

const res = await fetch(
  'https://api.smartmca.com/api/v1/settings/api-access/sandbox/activate',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${SESSION_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: '{}',
  }
);

const { sandboxOrgId, testApiKey } = await res.json();
console.log(`Sandbox org: ${sandboxOrgId}`);
console.log(`Test key: ${testApiKey.rawKey}`); // Save this — shown only once!

Using the Sandbox

Once activated, use your test API key exactly like a live key. All endpoints work the same way — the key prefix determines routing:

// This hits the SANDBOX
const TEST_KEY = 'smca_test_abc123...';

const deals = await fetch('https://api.smartmca.com/api/public/v1/deals', {
  headers: { 'Authorization': `Bearer ${TEST_KEY}` },
});

// This hits PRODUCTION
const LIVE_KEY = 'smca_live_xyz789...';

const realDeals = await fetch('https://api.smartmca.com/api/public/v1/deals', {
  headers: { 'Authorization': `Bearer ${LIVE_KEY}` },
});

Sample Data

When activated, the sandbox is seeded with:

• 3 sample merchants with realistic business details
• 3 deals at various lifecycle stages (active, paid off, collections)
• 1 month of payment history
• Collection schedules

Creating Additional Test Keys

You can create additional test API keys with different entity scopes:

1. Go to Settings → API Access
2. Click Create API Key
3. Select Test environment
4. Configure entity scope (funder admin, broker, syndicator, ISO)
5. Select scopes and create

Note: The “Test” environment option is only available when the sandbox is active.

Resetting Sandbox Data

Reset wipes all sandbox data and re-seeds with fresh sample records. API keys are preserved.

curl -X POST https://api.smartmca.com/api/v1/settings/api-access/sandbox/reset \
  -H "Authorization: Bearer ${SESSION_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}'

Checking Sandbox Status

curl https://api.smartmca.com/api/v1/settings/api-access/sandbox/status \
  -H "Authorization: Bearer ${SESSION_TOKEN}"

Response:

{
  "active": true,
  "sandboxOrgId": "org_sandbox_abc123",
  "createdAt": "2026-03-04T10:00:00Z",
  "keyCount": 2
}

Deactivating the Sandbox

Deactivation revokes all test API keys and stops billing. Sandbox data is retained for 30 days.

curl -X POST https://api.smartmca.com/api/v1/settings/api-access/sandbox/deactivate \
  -H "Authorization: Bearer ${SESSION_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{}'

After deactivation, any requests with test keys return:

{
  "code": "SANDBOX_NOT_ACTIVE",
  "message": "Sandbox environment is not active. Activate it in Settings → API Access."
}

Sandbox vs Production

Aspect	Sandbox (smca_test_*)	Production (smca_live_*)
Data	Sample/test data	Real data
Billing	Sandbox add-on fee	Normal subscription
Webhooks	Delivered normally	Delivered normally
Rate limits	Same as production	Same
API behavior	Identical	Identical

Best Practices

1. Test all flows in sandbox first before going live
2. Use environment variables to switch between test and live keys
3. Reset regularly to start with clean data for each test run
4. Test error handling — the sandbox behaves identically to production for errors
5. Test webhook signatures — sandbox webhooks use the same signing mechanism