Skip to main content

​
Overview

The CDP Payments API sandbox environment provides a safe, isolated testing space where you can develop and test your payment integrations without affecting production data or processing real transactions. The sandbox mirrors production functionality while using test data and simulated payment flows.
All API endpoints, authentication methods, and response formats in sandbox are identical to production, making it easy to transition your code when ready.

​
Key Differences: Sandbox vs Production

FeatureSandboxProduction
API Endpointapi.cdp.coinbase.com/sandboxapi.cdp.coinbase.com
API KeysSandbox-specific credentialsProduction credentials
TransactionsSimulated (no real value)Real payment processing
Test AccountsUnlimited test accountsReal user accounts
Rate LimitsSame as productionStandard production limits
Data PersistencePermanentPermanent
WebhooksNot AvailableProduction webhook URLs

​
Getting Started

​
1. Create Sandbox API Credentials

To access the sandbox environment, you’ll need to create sandbox-specific API credentials:
1

Access CDP Portal

Navigate to the CDP Portal
2

Select Your Project

Choose the project you want to create sandbox credentials for
3

Create Sandbox API Key

  • Go to API Keys section
  • Click Create API Key
  • Select Sandbox as the environment
  • Choose appropriate permissions (Accounts, Transfers, Payment Methods, etc.)
  • Save your API key name and private key securely
4

Configure Your Application

Update your application to use the sandbox endpoint and credentials
Important:
  • Never commit API keys to version control. Store them securely in environment variables or a secrets manager.
  • Real personal data must not be used in the sandbox environment.

​
2. Testing Workflows

Use following Postman Collection and Environment with the key created in previous step to test CDP Sandbox.

​
Best Practices

Keep sandbox configuration completely separate from production:
// config.ts
const config = {
  sandbox: {
    apiUrl: 'https://api.cdp.coinbase.com/sandbox',
    apiKey: process.env.CDP_SANDBOX_API_KEY,
  },
  production: {
    apiUrl: 'https://api.cdp.coinbase.com',
    apiKey: process.env.CDP_PRODUCTION_API_KEY,
  }
};

export const getConfig = () => {
  return process.env.NODE_ENV === 'production' 
    ? config.production 
    : config.sandbox;
};
Use sandbox to thoroughly test error scenarios:
  • Invalid authentication
  • Malformed requests
  • Rate limiting
  • Network timeouts
  • Insufficient funds
  • Invalid account details
Create automated test suites that run against sandbox:
// tests/integration/payments.test.ts
describe('Payments API Integration', () => {
  beforeAll(() => {
    // Set up sandbox client
  });
  
  test('should create account', async () => {
    const account = await createAccount({
      name: 'Test Account',
      currency: 'USD'
    });
    
    expect(account.id).toBeDefined();
    expect(account.currency).toBe('USD');
  });
  
  test('should process transfer', async () => {
    const transfer = await createTransfer({
      amount: '100.00',
      currency: 'USD'
    });
    
    expect(transfer.status).toBe('pending');
  });
});
Track your API usage patterns in sandbox to understand production requirements:
  • Request volumes
  • Response times
  • Error rates
  • Rate limit consumption

​
Limitations & Considerations

Be aware of these sandbox limitations when testing:
  • Performance: Response times may vary from production
  • Third-Party Services: Some third-party integrations use mocked responses
  • Rate Limits: Same rate limits as production apply to prevent abuse
  • Compliance Checks: Simplified compliance flows (no real KYC/AML)

​
Transitioning to Production

When you’re ready to move from sandbox to production:
1

Complete Integration Testing

Ensure all features work correctly in sandbox with comprehensive test coverage
2

Review Security Practices

  • Ensure API keys are stored securely
  • Review access control and permissions
  • Implement proper error handling
3

Create Production API Keys

Generate production credentials in the CDP Portal with appropriate permissions
4

Update Configuration

Switch from sandbox to production endpoints:
- baseURL: 'https://api.cdp.coinbase.com/sandbox'
+ baseURL: 'https://api.cdp.coinbase.com'
5

Start with Small Transactions

Begin with small test transactions to verify everything works as expected
6

Monitor Closely

Set up monitoring and alerting for:
  • Failed transactions
  • API errors
  • Unusual activity
7

Have a Rollback Plan

Be prepared to quickly revert to previous code if issues arise

​
Troubleshooting

Problem: Getting authentication errors in sandboxSolutions:
  • Verify you’re using sandbox API keys (not production)
  • Check that the API key has the required permissions
  • Ensure the Authorization header is properly formatted
  • Confirm the API key hasn’t expired
Problem: Hitting rate limits during testingSolutions:
  • Implement exponential backoff in your code
  • Add delays between rapid consecutive requests
  • Cache responses when appropriate
  • Contact support if you need higher limits for testing
Problem: Test transfers not completingSolutions:
  • Check the transfer amount (some amounts trigger delays)
  • Verify account IDs are valid sandbox accounts
  • Ensure you’ve called the execute endpoint
  • Review transfer status for error messages
Problem: Code works in sandbox but fails in productionSolutions:
  • Verify all configuration uses environment variables
  • Check for hardcoded sandbox-specific values
  • Ensure production API keys have correct permissions
  • Review any differences in account setup

​
Additional Resources

API Reference

Complete API documentation for all Payments API endpoints

Authentication Guide

Learn how to authenticate your API requests

CDP Portal

Manage your API keys and view analytics

​
Need Help?

If you encounter issues with the sandbox environment: