Skip to main content
The sandbox simulates the full Bluum environment — accounts, trading, funding, and webhooks. This guide covers how to test each part of your integration systematically.

​
Test scenarios by domain

​
Account creation

ScenarioHow to test
Successful creationSubmit valid account data → verify ACTIVE status
Validation failureOmit required fields → verify error response
Duplicate accountCreate two accounts with same email → verify 409 conflict

​
KYC verification

ScenarioHow to test
ApprovalUpload any valid image → auto-approved in sandbox
RejectionUse test rejection values (see dashboard)
Missing documentAttempt operations before KYC → verify error

​
Deposits

ScenarioHow to test
ACH successCreate deposit with valid Plaid options → transitions to completed
Manual transferCreate manual deposit → verify bank details in response
Insufficient fundsCreate withdrawal exceeding balance → verify 422 error
IdempotencySubmit same deposit twice with same key → verify no duplicate
Idempotency conflictSubmit different body with same key → verify error

​
Trading

ScenarioHow to test
Market buyPlace market order during hours → verify filled status
Limit orderPlace limit below market → remains accepted
Fractional buyUse notional for dollar-based purchase
Insufficient fundsPlace order exceeding wallet balance
Invalid symbolUse non-existent symbol → verify error

​
Webhooks

ScenarioHow to test
Event deliveryRegister webhook, place order → verify event received
Duplicate deliveryProcess same event twice → verify idempotent handling
Failure retryReturn 500 from webhook → verify Bluum retries

​
Sandbox-specific behaviors

​
Timing

  • Market orders fill instantly (no execution delay)
  • ACH deposits complete in seconds (not days)
  • KYC documents auto-approve immediately

​
Data reset

  • Sandbox data resets nightly at midnight UTC
  • All accounts, orders, and deposits are cleared
  • Webhook registrations persist across resets

​
Plaid sandbox

  • Use Plaid sandbox credentials (provided in your dashboard)
  • Test bank: “First Platypus Bank” with credentials user_good / pass_good

​
Integration test checklist

Run through this checklist before going live:
  • Account creation with all required fields
  • Account creation with missing fields (error handling)
  • KYC document upload and status check
  • Plaid Link token creation
  • Plaid public token exchange
  • ACH deposit with idempotency key
  • Manual bank transfer deposit
  • Deposit status tracking (polling or webhook)
  • Market buy order
  • Limit buy order
  • Position query after fill
  • Sell order
  • Withdrawal with idempotency key
  • Withdrawal cancellation
  • Webhook registration and event receipt
  • Error handling for all 4xx/5xx responses
  • Rate limit handling (429 with backoff)

​
Automated testing tips

// Use environment variables for easy switching
const config = {
  baseUrl: process.env.BLUUM_BASE_URL || 'https://test-service.bluumfinance.com/v1',
  apiKey: process.env.BLUUM_API_KEY,
  apiSecret: process.env.BLUUM_API_SECRET
};

// Generate unique idempotency keys per test run
const idempotencyKey = `test-${Date.now()}-${Math.random().toString(36).slice(2)}`;

// Clean up: note that sandbox resets nightly, but you may want to
// cancel pending orders and withdrawals between test runs

​
Next steps

When all tests pass, follow the Going Live checklist to move to production.