Skip to main content

​
Test and Live Modes

ZendFi uses a dual-mode architecture. Your API key prefix determines which Solana network processes the transaction. The code is identical in both modes — you only change the key.

​
How Modes Work

Test ModeLive Mode
Key prefixzfi_test_zfi_live_
NetworkSolana DevnetSolana Mainnet
TokensDevnet USDC/SOLReal USDC/USDT/SOL
TransactionsFree (no real value)Real funds
WebhooksFully functionalFully functional
Rate limitsSame as liveSame as test
API base URLhttps://api.zendfi.techhttps://api.zendfi.tech
Both modes use the same API base URL. The backend inspects your API key to route the request to the correct network. You never need to change URLs when going live.

​
SDK Mode Detection

The SDK automatically detects the mode from your API key: 
import { ZendFiClient } from '@zendfi/sdk';

// Test mode -- routes to devnet
const testClient = new ZendFiClient({
  apiKey: 'zfi_test_abc123',
});

// Live mode -- routes to mainnet
const liveClient = new ZendFiClient({
  apiKey: 'zfi_live_xyz789',
});
When using the zero-config singleton, it reads ZENDFI_API_KEY from the environment: 
import { zendfi } from '@zendfi/sdk';

// Mode is determined by the key in process.env.ZENDFI_API_KEY
const payment = await zendfi.createPayment({ amount: 50 });

​
Response Headers

Every API response includes a mode header so you can confirm which network processed the request: 
X-ZendFi-Mode: test
or 
X-ZendFi-Mode: live

​
Development Workflow

A typical workflow:
1

Develop with test keys

Use zfi_test_ keys during development. All transactions happen on Solana devnet with no real funds at risk.
2

Test webhooks locally

Use zendfi webhooks --port 3000 to tunnel webhooks to your local machine. Webhook payloads are identical between modes.
3

Deploy to staging

Deploy your app with test keys to a staging environment. Verify the full flow end-to-end.
4

Switch to live

Replace zfi_test_ with zfi_live_ in your production environment variables. No code changes required.

​
Environment Variable Patterns

Use a single environment variable and swap it per environment:
.env.development
ZENDFI_API_KEY=zfi_test_abc123
.env.production
ZENDFI_API_KEY=zfi_live_xyz789

​
Safety Warnings

The SDK includes built-in safety checks:
  • Using a live key in development logs a warning: real mainnet transactions will occur.
  • Using a test key in production logs a warning: only devnet transactions will be created.
These warnings appear in your server console to help catch environment misconfigurations before they become costly mistakes.

​
Testing with Devnet Funds

To complete test payments, you need devnet tokens:
  1. Devnet SOL: Use the Solana faucet to airdrop devnet SOL to your wallet.
  2. Devnet USDC: Swap devnet SOL for USDC using a devnet-compatible DEX, or use the devnet USDC faucet if available.
  3. Wallet setup: Configure Phantom, Solflare, or Backpack to use Solana devnet in settings.
ZendFi supports gasless transactions in both modes. Customers do not need SOL for gas fees — ZendFi sponsors the transaction costs.