Sandbox Environment

Test your Pelago integration in a risk-free sandbox environment before going live.

Overview

The sandbox environment mirrors production functionality with test networks and simulated transactions. No real cryptocurrency is used.

Environment	API Base URL	Networks
Sandbox	https://api.sandbox.pelago.tech	Stellar Testnet, Goerli
Production	https://api.pelago.tech	Stellar Mainnet, Ethereum

Getting Sandbox Credentials

1. Sign up at dashboard.pelago.tech
2. Navigate to Settings → API Keys
3. Toggle to Sandbox mode
4. Click Generate API Key

# Sandbox credentials have a 'test_' prefix
PELAGO_API_KEY=test_pk_xxxxxxxxxxxxx
PELAGO_API_SECRET=test_sk_xxxxxxxxxxxxx

Test Networks

Stellar Testnet

Get free testnet XLM for paying transaction fees:

# Use Stellar Friendbot to fund your test account
curl "https://friendbot.stellar.org/?addr=YOUR_TESTNET_ADDRESS"

Or visit: https://laboratory.stellar.org/#account-creator

Ethereum Goerli (for testing)

Get free Goerli ETH from faucets:

• https://goerlifaucet.com
• https://faucet.paradigm.xyz

Test Wallets

Use these test wallets for sandbox payments:

Network	Address	Notes
Stellar Testnet	GBXXXTEST...	Funded with testnet USDC
Goerli	0x000...TEST	Funded with test USDC

Making Test Payments

import { PelagoClient } from '@pelago/sdk';

const pelago = new PelagoClient({
  apiKey: process.env.PELAGO_API_KEY,
  apiSecret: process.env.PELAGO_API_SECRET,
  environment: 'sandbox' // 👈 Use sandbox mode
});

// Create a test payment
const payment = await pelago.payments.create({
  amount: 10.00,
  currency: 'USD',
  cryptocurrency: 'USDC',
  network: 'stellar-testnet', // 👈 Use testnet
  merchantWallet: 'YOUR_TESTNET_WALLET',
  metadata: { test: true }
});

Test Card (for Fiat → Crypto testing)

When testing fiat on-ramp flows, use these test card numbers:

Card Number	Result
4242 4242 4242 4242	Payment succeeds
4000 0000 0000 0002	Payment declined
4000 0000 0000 9995	Insufficient funds

Webhook Testing

Use webhook testing tools to inspect events:

1. ngrok - Expose local webhook endpoint

   ngrok http 3000
   # Use the https URL for your webhook configuration

2. Webhook.site - Inspect webhook payloads

   • Visit https://webhook.site
   • Copy your unique URL
   • Set as webhook URL in payment creation

Test Scenarios

Successful Payment

// Amount < 100 USD in sandbox always succeeds
const payment = await pelago.payments.create({
  amount: 50.00,
  // ...
});

Failed Payment

// Amount = 999.99 USD triggers a failure
const payment = await pelago.payments.create({
  amount: 999.99,
  // ...
});

Expired Payment

// Payments expire after 30 minutes by default
// Use 'expiresIn' to test shorter expiration
const payment = await pelago.payments.create({
  amount: 50.00,
  expiresIn: 60, // 60 seconds for testing
  // ...
});

Sandbox Limitations

Feature	Sandbox	Production
Real funds	❌ Test only	✅ Real crypto
Transaction speed	Instant	Network dependent
Rate limiting	100 req/min	1000 req/min
Webhook retries	3 retries	10 retries
Settlement	Simulated	Real

Going to Production

When you're ready to go live:

1. Switch to Production in the dashboard
2. Complete KYC verification
3. Generate production API keys
4. Update your environment variables
5. Replace sandbox with production in your code

const pelago = new PelagoClient({
  apiKey: process.env.PELAGO_API_KEY, // production key
  environment: 'production' // 👈 Switch to production
});

Next Steps

• Create Your First Payment
• Configure Webhooks