Skip to main content

Environments

Fiatsend provides two environments for integration: Sandbox for development and testing, and Production for live transactions with real funds. Both environments expose the same API surface, so code written against the sandbox works in production with only a configuration change.

This page covers the differences between environments, the required environment variables, and how to configure your application for each.

Sandbox​

The sandbox environment is a complete replica of the Fiatsend platform running against test infrastructure. No real money moves, no real mobile money transfers are initiated, and all blockchain transactions occur on Lisk Testnet.

PropertyValue
API Base URLhttps://sandbox-api.fiatsend.com
BlockchainLisk Testnet
Smart ContractSandbox-specific FiatsendGatewayV2 deployment
Mobile MoneySimulated providers (MTN, Telecel, AirtelTigo) — no real disbursements
KYCTest profiles available for all tiers (Level 0, 1, 2)
StablecoinsTestnet USDT, USDC, USDC.e, DAI, GHSFIAT (faucet available)
Rate LimitsRelaxed — higher thresholds for development
WebhooksFully functional with simulated events

Test KYC Profiles​

The sandbox includes pre-configured test profiles that let you simulate different KYC outcomes without submitting real documents:

Phone NumberKYC OutcomeTier
+233200000001Instantly verifiedLevel 1
+233200000002Instantly verifiedLevel 2
+233200000003Rejected (invalid document)Level 0
+233200000004Pending (manual review)Level 0

Test Mobile Money Numbers​

Use these sandbox phone numbers to simulate different payout outcomes:

Phone NumberProviderOutcome
+233241000001MTNSuccessful payout
+233201000001TelecelSuccessful payout
+233271000001AirtelTigoSuccessful payout
+233241000002MTNFailed — insufficient balance
+233241000003MTNFailed — invalid account
+233241000004MTNTimeout — delayed response
info

Sandbox test stablecoins can be obtained from the Fiatsend testnet faucet. Contact dev@fiatsend.com for faucet access and testnet tokens.

Production​

The production environment processes real transactions with real funds on Lisk Mainnet. Mobile money payouts are delivered to actual recipient wallets, and all blockchain transactions are final.

PropertyValue
API Base URLhttps://api.fiatsend.com
BlockchainLisk Mainnet
Smart ContractProduction FiatsendGatewayV2 (UUPS upgradeable)
Mobile MoneyLive providers — MTN Mobile Money, Telecel Cash, AirtelTigo
KYCReal identity verification with document review
StablecoinsUSDT, USDC, USDC.e, DAI, GHSFIAT (real assets)
Rate LimitsStrict — see Errors & Rate Limits
WebhooksLive event delivery with retry and signature verification
warning

Production transactions involve real funds and are irreversible. Always test your integration thoroughly in the sandbox before switching to production. Ensure your webhook signature verification is working correctly before going live.

Environment Variables​

The following environment variables are required to configure your Fiatsend integration. Values differ between sandbox and production.

VariableDescriptionSandbox ExampleProduction Example
NEXT_PUBLIC_BACKEND_ENDPOINTBackend API endpointhttps://sandbox-backend.fiatsend.comhttps://backend.fiatsend.com
NEXT_PUBLIC_BACKEND_PROJECT_IDBackend project identifiersandbox_project_abc123prod_project_xyz789
BACKEND_API_KEYServer-side backend API keysandbox_key_...prod_key_...
NEXT_PUBLIC_PRIVY_APP_IDPrivy application ID for wallet authclsandbox123...clprod789...
CONTRACT_ADDRESSFiatsendGatewayV2 smart contract address0x1234...abcd (Lisk Testnet)0x5678...efgh (Lisk Mainnet)
MOBILE_MONEY_API_KEYAPI key for mobile money provider gatewaymm_sandbox_key_...mm_prod_key_...
WEBHOOK_SECRETHMAC secret for verifying webhook signatureswhsec_sandbox_...whsec_prod_...
NEXT_PUBLIC_API_BASE_URLBase URL for Fiatsend API callshttps://sandbox-api.fiatsend.comhttps://api.fiatsend.com

Example .env.local​

Create a .env.local file in your project root with the appropriate values for your target environment:

.env.local
# Fiatsend Environment Configuration
# Switch between sandbox and production by changing these values

# Backend
NEXT_PUBLIC_BACKEND_ENDPOINT=https://sandbox-backend.fiatsend.com
NEXT_PUBLIC_BACKEND_PROJECT_ID=sandbox_project_abc123
BACKEND_API_KEY=sandbox_key_your_secret_key_here

# Privy (wallet authentication)
NEXT_PUBLIC_PRIVY_APP_ID=clsandbox123your_privy_app_id

# Smart Contract
CONTRACT_ADDRESS=0x1234567890abcdef1234567890abcdef12345678

# Mobile Money Provider Gateway
MOBILE_MONEY_API_KEY=mm_sandbox_key_your_key_here

# Webhooks
WEBHOOK_SECRET=whsec_sandbox_your_webhook_secret

# API Base URL
NEXT_PUBLIC_API_BASE_URL=https://sandbox-api.fiatsend.com
warning

Never commit secrets to version control. Add .env.local to your .gitignore file. Use a secrets manager (such as AWS Secrets Manager, Doppler, or Vercel Environment Variables) for production deployments. Never expose BACKEND_API_KEY, MOBILE_MONEY_API_KEY, or WEBHOOK_SECRET in client-side code. Never commit secrets to version control. Add .env.local to your .gitignore file. Use a secrets manager (such as AWS Secrets Manager, Doppler, or Vercel Environment Variables) for production deployments. Never expose BACKEND_API_KEY, MOBILE_MONEY_API_KEY, or WEBHOOK_SECRET in client-side code.

Switching Between Environments​

To move from sandbox to production:

  1. Replace all environment variable values with your production credentials.
  2. Update the API base URL from https://sandbox-api.fiatsend.com to https://api.fiatsend.com.
  3. Update the contract address to the production FiatsendGatewayV2 deployment on Lisk Mainnet.
  4. Update your webhook URL in the Fiatsend dashboard to point to your production webhook endpoint.
  5. Verify webhook signature verification is correctly configured with your production WEBHOOK_SECRET.
tip

Use environment-specific configuration files (e.g., .env.sandbox and .env.production) and load the appropriate one based on your deployment target. Most frameworks (Next.js, Vite, etc.) support environment-specific .env files out of the box.