Environments

FLUID Network provides two separate environments to support your development lifecycle: Sandbox for testing and Production for live transactions.

Overview

Environment	Purpose	Base URL
Sandbox	Development and testing	https://sandbox-api.fluid-network.com
Production	Live transactions	https://api.fluid-network.com

Sandbox Environment

Purpose

The Sandbox environment is a fully-functional testing environment that mirrors production capabilities without processing real transactions or charging real accounts.

Key Features

• No Real Money: All transactions are simulated
• Full API Access: All endpoints available, same as production
• Test Data: Pre-populated with test banks and accounts
• No Side Effects: Safe to test edge cases and error scenarios
• Webhook Testing: Webhooks work exactly as in production

Base URL

https://sandbox-api.fluid-network.com/api/v1/payment-providers/

Sandbox API Keys

Sandbox API keys are prefixed with test_sk_:

# Example sandbox API key
test_sk_1234567890abcdef

Test Data

The Sandbox environment includes test data for common scenarios:

Test Banks

Bank Name	Identifier	Country
Test Bank Ghana	TST	GH
Example Bank Test	EXB	GH
Demo Bank Test	DEM	GH

Test Phone Numbers

Use these phone numbers for testing different scenarios:

Phone Number	Scenario	Expected Behavior
+233241234567	Success	Transaction completes successfully
+233241234568	Pending	Transaction stays pending (for testing timeouts)
+233241234569	Failed	Transaction fails (insufficient funds)
+233241234570	Rejected	Customer rejects the transaction

Test Amounts

Certain amounts trigger specific behaviors:

Amount	Behavior
1.00 - 9999.99	Success
10000.00	Insufficient funds error
10001.00	Transaction timeout
10002.00	Bank system error

Sandbox Limitations

Important Considerations:

The Sandbox environment has some limitations:

• Rate limits are lower (30 requests/minute vs 60 in production)
• Data is reset periodically (monthly)
• Performance may be slower than production
• Some advanced features may have simulated responses

Production Environment

Purpose

The Production environment processes real transactions with actual customer accounts and bank systems.

Base URL

https://api.fluid-network.com/api/v1/payment-providers/

Production API Keys

Production API keys are prefixed with live_sk_:

# Example production API key
live_sk_1234567890abcdef

Requirements

Before using the Production environment:

1. Complete Onboarding - Finish business verification and compliance
2. Test in Sandbox - Thoroughly test integration in Sandbox
3. Security Review - Pass security and integration review
4. Receive Production Keys - Get production API credentials from FLUID team

Production Considerations

IMPORTANT:

• All transactions in production are real and irreversible
• Failed transactions may incur bank fees
• Rate limits are strictly enforced
• Security measures (IP whitelisting, HMAC) are strongly recommended
• Monitor error rates and transaction status closely

Switching Between Environments

Using Environment Variables

The recommended approach is to use environment variables to configure your application for different environments.

Development Environment (.env.development):

# Development environment
FLUID_API_KEY=test_sk_1234567890abcdef
FLUID_BASE_URL=https://sandbox-api.fluid-network.com
FLUID_ENVIRONMENT=sandbox

Production Environment (.env.production):

# Production environment
FLUID_API_KEY=live_sk_9876543210fedcba
FLUID_BASE_URL=https://api.fluid-network.com
FLUID_ENVIRONMENT=production

Implementation Notes

Configuration Validation:

Your application should validate that the API key matches the environment:

1. Production Environment Checks:

   • Verify API key starts with live_sk_ prefix
   • Throw an error if sandbox key is used in production
   • Require explicit production confirmation flags

2. Sandbox Environment Checks:

   • Verify API key starts with test_sk_ prefix
   • Log a warning if production key is used in sandbox
   • Allow more flexible testing configurations

3. Key Security:

   • Never hardcode API keys in your application code
   • Load keys from environment variables or secure configuration stores
   • Use different key management strategies per environment

Environment-Specific Behavior

Rate Limiting

Environment	Requests per Minute	Burst Limit
Sandbox	30	50
Production	60	100

See Rate Limiting Guide for details.

Webhooks

Both environments support webhooks, but use different URLs:

# Sandbox webhooks
https://sandbox-api.fluid-network.com/webhooks/events

# Production webhooks  
https://api.fluid-network.com/webhooks/events

Error Codes

Error codes are identical across environments, but Production may include additional bank-specific error details.

Best Practices

Development Workflow

1. Start in Sandbox: Develop and test all features in Sandbox first
2. Test Edge Cases: Use test phone numbers and amounts to simulate errors
3. Load Test: Verify your integration handles rate limits
4. Security Test: Enable HMAC and IP whitelisting in Sandbox before production
5. Staging Environment: Create a staging environment that uses Sandbox
6. Production Deployment: Only deploy to production after thorough Sandbox testing

Monitoring

Set up monitoring for both environments:

Implementation Approach:

1. Log environment context with each API request for debugging and auditing
2. Track environment-specific metrics to monitor behavior differences between Sandbox and Production
3. Set up alerts for unexpected environment usage patterns (e.g., production calls from test systems)
4. Use structured logging to include environment, endpoint, and request metadata

Safety Checks

Implement safety checks to prevent accidental production usage:

Recommended Safety Mechanisms:

1. Explicit Production Confirmation:

   • Require an additional environment variable (e.g., CONFIRM_PRODUCTION=true) to enable production mode
   • Throw an error if production environment is used without explicit confirmation
   • Document this requirement in your deployment procedures

2. CI/CD Protection:

   • Prevent production API calls from running in automated test environments
   • Check for CI environment variables (e.g., CI=true) and block production usage
   • Use Sandbox exclusively for automated testing

3. API Key Validation:

   • Verify the API key prefix matches the declared environment
   • Fail fast with clear error messages if there's a mismatch
   • Log all environment/key mismatches for security auditing

Transition Checklist

Before moving from Sandbox to Production:

• ✅ All integration tests pass in Sandbox
• ✅ Error handling tested with all error scenarios
• ✅ Webhook endpoints verified and tested
• ✅ Rate limiting handled gracefully
• ✅ Security measures implemented (HMAC, IP whitelisting)
• ✅ Monitoring and alerting configured
• ✅ Production API keys stored securely
• ✅ Team trained on production procedures
• ✅ Rollback plan documented
• ✅ FLUID Network integration review completed

Need Help?

• Sandbox Issues: Email sandbox@fluidnetwork.africa
• Production Access: Email support@fluidnetwork.africa
• Technical Questions: See our support page

Next Steps

Quickstart →

Make your first API call in Sandbox

API Reference →

Explore available endpoints