Sandbox Testing

The Grid Sandbox environment provides a complete testing environment for ramp operations, allowing you to validate on-ramp and off-ramp flows without using real money or cryptocurrency.

Sandbox overview

Sandbox mirrors production behavior while using simulated funds:

Same API endpoints: Use identical API calls as production
Simulated funding: Mock bank transfers and crypto deposits
Real webhooks: Receive actual webhook notifications
No real money: All transactions use test funds
Isolated environment: Sandbox data never affects production

Sandbox is perfect for development, testing, and demonstrating ramp functionality before going live.

Getting started

Create sandbox credentials

Log into the Grid dashboard
Navigate to Settings → API Keys
Click Create API Key and select Sandbox environment
Save your API key ID and secret securely

Sandbox credentials only work with the sandbox environment. They cannot access production data or move real funds.

Configure sandbox webhook

Set up a webhook endpoint for sandbox notifications:

curl -X PATCH 'https://api.lightspark.com/grid/2025-10-13/config' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "webhookEndpoint": "https://api.yourapp.dev/webhooks/grid"
  }'

Use tools like ngrok to expose local webhook endpoints during development: ngrok http 3000

Testing on-ramps (Fiat → Crypto)

Simulate the complete on-ramp flow in sandbox:

Step 1: Create a test customer

curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "platformCustomerId": "test_user_001",
    "customerType": "INDIVIDUAL",
    "fullName": "Alice Test",
    "email": "alice@example.com",
    "birthDate": "1990-01-15",
    "address": {
      "line1": "123 Test Street",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "country": "US"
    }
  }'

In sandbox, customers are automatically approved for testing.

Step 2: Create an external account for the destination wallet

curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers/external-accounts' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId": "Customer:sandbox001",
    "currency": "BTC",
    "accountInfo": {
      "accountType": "SPARK_WALLET",
      "address": "spark1pgssyuuuhnrrdjswal5c3s3rafw9w3y5dd4cjy3duxlf7hjzkp0rqx6dj6mrhu"
    }
  }'

Step 3: Create an on-ramp quote (just-in-time funding)

curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "source": {
      "customerId": "Customer:sandbox001",
      "currency": "USD"
    },
    "destination": {
      "destinationType": "ACCOUNT",
      "accountId": "ExternalAccount:b23dcbd6-dced-4ec4-b756-3c3a9ea3d456"
    },
    "lockedCurrencySide": "SENDING",
    "lockedCurrencyAmount": 10000,
    "description": "Test on-ramp conversion"
  }'

The quote response includes payment instructions with a reference code.

Step 4: Simulate funding

Use the sandbox endpoint to simulate receiving the fiat payment:

curl -X POST 'https://api.lightspark.com/grid/2025-10-13/sandbox/send' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "reference": "RAMP-ABC123",
    "currencyCode": "USD",
    "currencyAmount": 10000
  }'

The reference code must match the one provided in the quote’s payment instructions.

Step 5: Verify completion

Within seconds, you’ll receive a webhook notification confirming the on-ramp completed:

{
  "transaction": {
    "id": "Transaction:sandbox025",
    "status": "COMPLETED",
    "type": "OUTGOING",
    "sentAmount": {
      "amount": 10000,
      "currency": { "code": "USD" }
    },
    "receivedAmount": {
      "amount": 95000,
      "currency": { "code": "BTC" }
    },
    "settledAt": "2025-10-03T15:02:30Z"
  },
  "type": "OUTGOING_PAYMENT"
}

Testing off-ramps (Crypto → Fiat)

Simulate the complete off-ramp flow:

Step 1: Fund internal account with crypto

Simulate a Bitcoin deposit to the customer’s internal account using the sandbox funding endpoint:

curl -X POST 'https://api.lightspark.com/grid/2025-10-13/sandbox/internal-accounts/InternalAccount:btc001/fund' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 10000000
  }'

Replace InternalAccount:btc001 with your actual BTC internal account ID.

You’ll receive an ACCOUNT_STATUS webhook showing the updated balance.

Step 2: Create external bank account

curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers/external-accounts' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId": "Customer:sandbox001",
    "currency": "USD",
    "platformAccountId": "test_bank_001",
    "accountInfo": {
      "accountType": "US_ACCOUNT",
      "accountNumber": "123456001",
      "routingNumber": "021000021",
      "accountCategory": "CHECKING",
      "bankName": "Test Bank",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Alice Test",
        "birthDate": "1990-01-15",
        "nationality": "US",
        "address": {
          "line1": "123 Test Street",
          "city": "San Francisco",
          "state": "CA",
          "postalCode": "94105",
          "country": "US"
        }
      }
    }
  }'

In sandbox, you can use special account number patterns to test different scenarios. The last 3 digits determine the behavior: 002 (insufficient funds), 003 (account closed), 004 (transfer rejected), 005 (timeout/delayed failure). Any other ending succeeds normally. See “Testing transfer failures” below for details.

Step 3: Create and execute off-ramp quote

curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "source": {
      "accountId": "InternalAccount:sandbox_btc001"
    },
    "destination": {
      "accountId": "ExternalAccount:sandbox_bank001",
      "currency": "USD"
    },
    "lockedCurrencySide": "SENDING",
    "lockedCurrencyAmount": 5000000,
    "description": "Test off-ramp conversion"
  }'

Then execute the quote:

curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes/{quoteId}/execute' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"

In sandbox, off-ramp conversions complete instantly. In production, bank settlement may take 1-3 business days.

Testing transfer failures

External account test patterns

The flows for creating external accounts in sandbox are the same as in production. The last 3 digits of an external account’s primary identifier (account number, IBAN, CLABE, Spark wallet address, etc.) determine the test scenario when that account is used in transfers or quotes. For identifiers with a domain part (e.g. PIX email keys), append the test digits to the username portion — for example, testuser.002@pix.com.br.

Suffix	Behavior
002	Insufficient funds — transfer fails immediately
003	Account closed/invalid — transfer fails immediately
004	Transfer rejected — bank rejects the transfer
005	Timeout/delayed failure — stays pending ~30s, then fails
Any other	Success — transfer completes normally

Beneficiary name verification

For account types that support beneficiary name verification, you can simulate different verification outcomes in sandbox. Use account identifiers with a 1xx suffix to trigger verification scenarios (this range is reserved for verification and does not conflict with transfer or quote test patterns):

Suffix	`beneficiaryVerificationStatus`	Behavior
102	`NOT_MATCHED`	Account is valid but name does not match
103	`PARTIAL_MATCH`	Account is valid, name is a fuzzy match
104	`PENDING`	Verification still in progress
105	(error)	Returns `400` — invalid account
106	`UNSUPPORTED`	Payment rail does not support name verification
107	`CHECKED_BY_RECEIVING_FI`	Verification deferred to receiving financial institution (e.g., ACH)
109	(error)	Returns `500` — simulated API error
Any other	`MATCHED`	Account is valid, name matches exactly

Test scenarios

Successful conversions

The complete on-ramp and off-ramp flows described in the sections above demonstrate successful conversion scenarios. For quick reference: On-ramp test (USD → BTC):

Create customer and quote with payment instructions
Use /sandbox/send to simulate funding
Verify completion via webhook

Off-ramp test (BTC → USD):

Fund BTC internal account with /sandbox/internal-accounts/{accountId}/fund
Create external bank account (use default account number for success)
Create and execute quote
Verify completion via webhook

Failed conversions

Test error scenarios systematically using the magic account patterns: 1. Test external account insufficient funds (002):

# Create account with insufficient funds pattern
curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers/external-accounts' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "customerId": "Customer:sandbox001",
    "currency": "USD",
    "accountInfo": {
      "accountType": "US_ACCOUNT",
      "accountNumber": "000000002",
      "routingNumber": "021000021",
      "accountCategory": "CHECKING",
      "beneficiary": {
        "beneficiaryType": "INDIVIDUAL",
        "fullName": "Test User"
      }
    }
  }'

# Attempt off-ramp to this account - will fail immediately
curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes/{quoteId}/execute' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET"
# Response: 400 Bad Request with insufficient funds error

2. Test account closed (003):

# Create account with closed pattern
curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers/external-accounts' \
  -d '{"accountNumber": "000000003", ...}'

# Attempt to use - will fail with account closed error

3. Test insufficient balance in internal account:

# Create quote from empty internal account
curl -X POST 'https://api.lightspark.com/grid/2025-10-13/quotes' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "source": {
      "accountId": "InternalAccount:empty_btc"
    },
    "destination": {
      "accountId": "ExternalAccount:bank001",
      "currency": "USD"
    },
    "lockedCurrencySide": "SENDING",
    "lockedCurrencyAmount": 10000000
  }'

# Execute will fail with insufficient balance error

4. Test invalid wallet address:

# Attempt to create an external account with invalid Spark address
curl -X POST 'https://api.lightspark.com/grid/2025-10-13/customers/external-accounts' \
  -u "$GRID_CLIENT_ID:$GRID_CLIENT_SECRET" \
  -H 'Content-Type: application/json' \
  -d '{
    "currency": "BTC",
    "accountInfo": {
      "accountType": "SPARK_WALLET",
      "address": "invalid_address"
    }
  }'
# Response: 400 Bad Request with validation error

Moving to Production

When you’re ready to move to production:

Generate production API tokens in the dashboard
Swap those credentials for the sandbox credentials in your environment variables
Remove any sandbox-specific test patterns from your code
Configure production webhook endpoints
Test with small amounts first

Next steps

Webhooks - Handle real-time notifications
Fiat-to-Crypto Conversion - Implement production flows
Self-Custody Wallets - Advanced wallet integration
Platform Configuration - Configure production settings
API Reference - Complete API documentation

Overview

Onboarding

Managing Accounts

Conversion Flows

Platform Tools

Sandbox overview

Getting started

Create sandbox credentials

Configure sandbox webhook

Testing on-ramps (Fiat → Crypto)

Step 1: Create a test customer

Step 2: Create an external account for the destination wallet

Step 3: Create an on-ramp quote (just-in-time funding)

Step 4: Simulate funding

Step 5: Verify completion

Testing off-ramps (Crypto → Fiat)

Step 1: Fund internal account with crypto

Step 2: Create external bank account

Step 3: Create and execute off-ramp quote

Testing transfer failures

External account test patterns

Beneficiary name verification

Test scenarios

Successful conversions

Failed conversions

Moving to Production

Next steps

Overview

Onboarding

Managing Accounts

Conversion Flows

Platform Tools

Documentation Index

​Sandbox overview

​Getting started

​Create sandbox credentials

​Configure sandbox webhook

​Testing on-ramps (Fiat → Crypto)

​Step 1: Create a test customer

​Step 2: Create an external account for the destination wallet

​Step 3: Create an on-ramp quote (just-in-time funding)

​Step 4: Simulate funding

​Step 5: Verify completion

​Testing off-ramps (Crypto → Fiat)

​Step 1: Fund internal account with crypto

​Step 2: Create external bank account

​Step 3: Create and execute off-ramp quote

​Testing transfer failures

​External account test patterns

​Beneficiary name verification

​Test scenarios

​Successful conversions

​Failed conversions

​Moving to Production

​Next steps

Sandbox overview

Getting started

Create sandbox credentials

Configure sandbox webhook

Testing on-ramps (Fiat → Crypto)

Step 1: Create a test customer

Step 2: Create an external account for the destination wallet

Step 3: Create an on-ramp quote (just-in-time funding)

Step 4: Simulate funding

Step 5: Verify completion

Testing off-ramps (Crypto → Fiat)

Step 1: Fund internal account with crypto

Step 2: Create external bank account

Step 3: Create and execute off-ramp quote

Testing transfer failures

External account test patterns

Beneficiary name verification

Test scenarios

Successful conversions

Failed conversions

Moving to Production

Next steps