Sandbox Testing

The MLM Platform provides sandbox environments for safe testing without affecting production data.

Overview

Sandbox environments allow you to:

Test API integrations without real transactions
Simulate purchases and commission flows
Create test users and hierarchies
Reset data for clean test runs

Creating a Sandbox

Navigate to Settings > Environments in the Admin Dashboard
Click Create Sandbox
Enter a label (e.g., “Development”, “QA”)
Optionally connect Stripe test mode
Click Create

You can create up to 3 sandbox environments per tenant.

Sandbox API Keys

Each sandbox has its own API keys:

Go to Settings > API Keys
Click Create API Key
Select your sandbox environment
Copy the key (prefix: mlm_sandbox_)

Simulating Purchases

Use your sandbox API key to record purchase events safely:

curl -X POST https://app.mlm-platform.com/api/v1/events/purchase \
  -H "Content-Type: application/json" \
  -H "x-tenant-api-key: mlm_sandbox_abc123" \
  -d '{
    "user_id": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 99.99,
    "currency": "USD",
    "description": "[SANDBOX] Test purchase"
  }'

const response = await fetch(
  'https://app.mlm-platform.com/api/v1/events/purchase',
  {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-tenant-api-key': 'mlm_sandbox_abc123'
    },
    body: JSON.stringify({
      user_id: '550e8400-e29b-41d4-a716-446655440000',
      amount: 99.99,
      currency: 'USD',
      description: '[SANDBOX] Test purchase'
    })
  }
);

const result = await response.json();
console.log('Commissions created:', result.commissions_created);

Response:

{
  "purchase_id": "660e8400-e29b-41d4-a716-446655440001",
  "commissions_created": 3,
  "commission_details": [
    {
      "beneficiary_id": "550e8400-e29b-41d4-a716-446655440002",
      "level": 1,
      "rate": 0.10,
      "amount": 9.999
    },
    {
      "beneficiary_id": "550e8400-e29b-41d4-a716-446655440003",
      "level": 2,
      "rate": 0.05,
      "amount": 4.9995
    }
  ]
}

Creating Test Users

Create test users for building hierarchies:

// Create a test user hierarchy
const root = await client.createTestUser({
  email: 'root@test.com',
  membershipTier: 'SENIOR'
});

const level1 = await client.createTestUser({
  email: 'level1@test.com',
  membershipTier: 'ORDINARY',
  parentId: root.id
});

const level2 = await client.createTestUser({
  email: 'level2@test.com',
  membershipTier: 'ORDINARY',
  parentId: level1.id
});

// Simulate a purchase by level2
const result = await client.simulatePurchase({
  buyerUserId: level2.id,
  amount: 100.00
});

// root and level1 should receive commissions
console.log('Commissions:', result.commission_details);

Resetting Sandbox Data

To reset your sandbox, use the Admin Dashboard to reset or recreate your sandbox environment.

Cloning Configuration

Copy your production commission rules to sandbox:

await client.cloneConfigToSandbox({
  targetEnvironmentId: 'sandbox-environment-id'
});

This copies:

Commission rules and rates
Tier configurations
Payout settings

It does not copy:

User data
Commission history
API keys or credentials

Testing Stripe Integration

Connect Stripe Test Mode

Go to Settings > Environments
Select your sandbox
Click Connect Stripe
Use Stripe test mode credentials

Test payout paths (sandbox only)

On Tenant Admin → Payouts (/tenant-admin/payouts):

Configure Stripe → Wise auto top-up (Stripe external account ID + Wise balance ID)
Ensure sandbox Stripe keys, Wise sandbox profile, and test members with payout accounts exist
Use Test Wise payout path or Test Stripe Connect payout path to exercise the full automated pipeline

These buttons invoke the sandbox-payout-e2e-test edge function and record step-by-step results.

Commission clearing in sandbox

Commissions clear from PENDING → CLEARED when:

Purchase metadata has no stripe_payment_intent_id (clears on next sync), or
Stripe reports the linked PaymentIntent’s balance transaction as available

Clearing is triggered by sync-stripe-commission-clearing (daily cron). Manual payout runs on Payouts invoke ensure-wise-balance then resolve-payouts. Calls8 integrations should pass stripe_payment_intent_id in purchase metadata so card-funded commissions wait for Stripe settlement.

Test Card Numbers

Card Number	Result
`4242 4242 4242 4242`	Success
`4000 0000 0000 0002`	Decline
`4000 0000 0000 9995`	Insufficient funds
`4000 0000 0000 0069`	Expired card

Test Webhooks

Use Stripe CLI to forward test webhooks:

stripe listen --forward-to localhost:3000/api/v1/webhooks/stripe?tenant_id=YOUR_TENANT_ID

# In another terminal
stripe trigger checkout.session.completed

Environment Detection

Verify you’re in sandbox mode:

const response = await fetch('/api/users', {
  headers: { 'x-tenant-api-key': apiKey }
});

const environment = response.headers.get('X-Environment');
console.log('Environment:', environment); // "SANDBOX"

Best Practices

Separate Test Data

Use distinct email patterns: test-*@example.com
Use recognizable product names: [TEST] Product Name
Add metadata: { "test": true, "scenario": "happy-path" }

Automated Testing

describe('Commission Flow', () => {
  beforeEach(async () => {
    // Reset sandbox before each test
    await client.resetSandbox();
  });
  
  it('should create commissions for upline', async () => {
    // Create hierarchy
    const sponsor = await client.createTestUser({ email: 'sponsor@test.com' });
    const buyer = await client.createTestUser({ 
      email: 'buyer@test.com',
      parentId: sponsor.id
    });
    
    // Simulate purchase
    const result = await client.simulatePurchase({
      buyerUserId: buyer.id,
      amount: 100.00
    });
    
    // Verify commissions
    expect(result.commissions_created).toBe(1);
    expect(result.commission_details[0].beneficiary_id).toBe(sponsor.id);
  });
});

CI/CD Integration

# .github/workflows/test.yml
jobs:
  integration-tests:
    runs-on: ubuntu-latest
    env:
      MLM_API_KEY: ${{ secrets.MLM_SANDBOX_API_KEY }}
    steps:
      - uses: actions/checkout@v4
      - run: npm ci
      - run: npm run test:integration

Get Started

Guides

SDKs

Sandbox Testing

Sandbox Testing

Overview

Creating a Sandbox

Sandbox API Keys

Simulating Purchases

Creating Test Users

Resetting Sandbox Data

Cloning Configuration

Testing Stripe Integration

Connect Stripe Test Mode

Test payout paths (sandbox only)

Commission clearing in sandbox

Test Card Numbers

Test Webhooks

Environment Detection

Best Practices

Separate Test Data

Automated Testing

CI/CD Integration

​Sandbox Testing

​Overview

​Creating a Sandbox

​Sandbox API Keys

​Simulating Purchases

​Creating Test Users

​Resetting Sandbox Data

​Cloning Configuration

​Testing Stripe Integration

​Connect Stripe Test Mode

​Test payout paths (sandbox only)

​Commission clearing in sandbox

​Test Card Numbers

​Test Webhooks

​Environment Detection

​Best Practices

​Separate Test Data

​Automated Testing

​CI/CD Integration

Sandbox Testing

Overview

Creating a Sandbox

Sandbox API Keys

Simulating Purchases

Creating Test Users

Resetting Sandbox Data

Cloning Configuration

Testing Stripe Integration

Connect Stripe Test Mode

Test payout paths (sandbox only)

Commission clearing in sandbox

Test Card Numbers

Test Webhooks

Environment Detection

Best Practices

Separate Test Data

Automated Testing

CI/CD Integration