Sandbox Configuration and Activation
This guide explains how to set up and activate your FinHub sandbox environment, allowing you to test and develop your integration before moving to production.
Sandbox Overview
The FinHub sandbox is a fully functional testing environment that mimics the production environment. It allows you to:
- Test API integrations without affecting real data or transactions
- Explore API capabilities and features
- Develop and debug your integration
- Validate your implementation against FinHub requirements
Prerequisites
Before configuring your sandbox, ensure you have:
- Completed the registration process as a FinHub API client
- Received your sandbox tenant credentials via email
- Access to the FinHub Developer Portal
Sandbox Characteristics
| Feature | Sandbox Behavior |
|---|
| Data | Test data only, regularly reset |
| Transactions | Simulated, no real money movement |
| KYC/KYB | Simplified verification for testing |
| Rate Limits | Relaxed limits for development |
| Notifications | Sent to test endpoints only |
| Payment Networks | Simulated/test environments |
Sandbox Configuration Steps
Step 1: Access the Developer Portal
Log in to the FinHub Sandbox Portal using the credentials provided during registration:
- Navigate to
https://sandbox.finhub.cloud
- Enter your sandbox username and password
- Complete any required verification
Step 2: Create a Sandbox Tenant
- Navigate to the “Sandbox” section in the Developer Portal
- Click “Create New Sandbox Tenant”
- Fill in the required information:
- Tenant name
- Technical contact information
- Selected products for testing
- Submit the form to create your sandbox tenant
- Once your sandbox tenant is created, navigate to the “API Access” section
- Generate your client credentials:
- Client ID: Your unique identifier for API requests
- Client Secret: Your secret key (keep this secure!)
- Note down these credentials as they will be required for authentication
Store your credentials securely - the Client Secret is shown only once. If lost, you’ll need to regenerate it.
- Go to the “Security” section in the Developer Portal
- Add the IP addresses of your development and testing environments
- Save your changes
IP whitelisting is required for both sandbox and production environments. Ensure all development, staging, and CI/CD environments are whitelisted.
- Navigate to the “Webhooks” section
- Add the URLs where FinHub should send event notifications
- Configure the events you want to receive
- Test the webhook connection using the “Send Test Event” feature
Step 6: Activate Your Sandbox
After completing the configuration:
- Go to the “Activation” section
- Review your configuration settings
- Click “Activate Sandbox”
- Confirm the activation
Your sandbox will be activated within 15 minutes, and you’ll receive a confirmation email with your sandbox details.
Environment Variables
Set up your development environment with these variables:
# FinHub Sandbox Configuration
FINHUB_BASE_URL=https://gateway.sandbox.finhub.cloud
FINHUB_TENANT_ID=your_tenant_id
FINHUB_CLIENT_ID=your_client_id
FINHUB_CLIENT_SECRET=your_client_secret
FINHUB_USERNAME=your_sandbox_username
FINHUB_PASSWORD=your_sandbox_password
# Webhook Configuration (Optional)
FINHUB_WEBHOOK_SECRET=your_webhook_secret
Test Data
The sandbox comes pre-configured with test data for common testing scenarios:
| Data Type | Description |
|---|
| Test Customers | Pre-created individual and business customers |
| Test Accounts | Accounts with test balances |
| Test Cards | Virtual cards for testing |
| Test IBANs | IBANs for payment testing |
| Test Documents | Sample KYC documents |
Test Card Numbers
| Card Type | Number | Use Case |
|---|
| Visa | 4111 1111 1111 1111 | Successful transactions |
| Mastercard | 5555 5555 5555 4444 | Successful transactions |
| Visa | 4000 0000 0000 0002 | Declined transactions |
| Mastercard | 5100 0000 0000 0004 | Insufficient funds |
Test Bank Accounts
| IBAN | Bank | Use Case |
|---|
| DE89370400440532013000 | Deutsche Bank (Test) | Successful SEPA transfers |
| GB82WEST12345698765432 | Test Bank UK | Successful UK transfers |
| FR7630006000011234567890189 | Test Bank FR | Failed transfers (test) |
Sandbox Limitations
Be aware of these limitations when testing your integration.
- Transaction Limits: Lower transaction limits than production
- Simulated Behavior: Some features have simulated behavior
- External Integrations: Card networks and bank connections use test environments
- Response Times: May differ from production
- Data Resets: Data may be reset periodically (typically monthly)
Quick Verification
# Get an access token
curl -X POST "https://gateway.sandbox.finhub.cloud/api/v2/auth/sandbox/token" \
-H "Content-Type: application/json" \
-H "X-Tenant-ID: your_tenant_id" \
-d '{
"username": "your_username",
"password": "your_password",
"customerId": "your_customer_id",
"customerSecret": "your_customer_secret",
"accountType": "b2c"
}'
# Test with the received token
curl -X GET "https://gateway.sandbox.finhub.cloud/api/v2/settings/countries" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json"
Next Steps
