Skip to main content
Crypto Checkout has a built-in test mode designed for developing and validating your integration without moving real funds. Test mode uses the same API surface as live mode, so everything you build and verify during development works identically in production — you simply swap the API key.

​
Test mode vs. live mode

The mode is determined entirely by the API key you use. There is no separate environment URL or configuration flag.
Test modeLive mode
API key prefixck_test_...ck_live_...
Session livemode fieldfalsetrue
ChainsTestnets (Sepolia, Base Sepolia, etc.)Mainnets (Ethereum, Base, etc.)
Dashboard viewTest events onlyLive events only
Real funds movedNeverYes
Generate keys in Dashboard → API Keys. Select Test or Live when creating the key — you cannot change the mode of an existing key.
Your ck_live_... key authorises real on-chain transactions. Keep it in a secret manager and never commit it to source control or expose it in client-side code.

​
Supported testnet chains

Enable testnet chains alongside your mainnet chains in Dashboard → Networks. Each testnet mirrors its mainnet counterpart’s behaviour.
NetworkTestnet nameChain ID
EthereumSepolia11155111
BaseBase Sepolia84532
ArbitrumArbitrum Sepolia421614
OptimismOptimism Sepolia11155420
PolygonPolygon Amoy80002
SolanaDevnet103
TronNile testnet2494104990
BitcoinSignet38333

​
Getting testnet funds

Each network provides a public faucet for free testnet tokens:
Faucet availability and rate limits change frequently. If one faucet is down, search for [network] testnet faucet — several community faucets usually exist for each chain.

​
Running a test payment end-to-end

1
Create a session with a test key
2
Use your ck_test_... key and specify a testnet chain ID:
3
curl -X POST https://your-domain.com/api/v1/checkout_sessions \
  -H "Authorization: Bearer ck_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: test-order-001-v1" \
  -d '{
    "amount": { "value": "1.00", "currency": "USD" },
    "metadata": { "testRun": true }
  }'
4
The response will include "livemode": false and a testnet deposit address.
5
Send testnet tokens from your wallet
6
Open MetaMask (or any compatible wallet) and switch it to the matching testnet. Scan the QR code on the checkout page or copy the deposit address and send the exact required amount.
7
Watch the session progress in the dashboard
8
Open Dashboard → Sessions and observe the status transitions in real time:
9
pending → detected → paid
10
The transition from detected to paid happens once the required number of confirmations (default: 3) are reached. On testnets this typically takes 30–90 seconds.
11
Verify webhook delivery
12
Open Dashboard → Webhooks, select your endpoint, and check the Delivery log tab. You should see a session.paid delivery with a 200 response from your handler.
13
If your local dev server is not publicly reachable, expose it with ngrok http 8256 and register the tunnel URL as your webhook endpoint.

​
Sending a synthetic webhook event

You can trigger a session.paid delivery without making any real payment using the test endpoint. This is useful for testing your webhook handler in isolation. 
curl -X POST https://your-domain.com/api/v1/webhook_endpoints/{id}/test \
  -H "Authorization: Bearer ck_test_YOUR_KEY"
The response returns a delivery ID: 
{ "deliveryId": "del_01HZ..." }
The synthetic session.paid event is queued immediately and delivered to your endpoint. Check the delivery log in Dashboard → Webhooks → endpoint detail to see the request and response.
Synthetic events use a placeholder session object and are marked livemode: false. They are intended for testing your signature verification and handler logic, not for end-to-end payment flow testing.

​
Switching to live mode

When you are satisfied with your integration on testnet, switching to production takes three steps:
  1. Generate a ck_live_... key in Dashboard → API Keys (select Live mode)
  2. Update your environment variable — replace CHECKOUT_API_KEY=ck_test_... with the new live key
  3. Enable mainnet chains in Dashboard → Networks and confirm your payout wallet addresses in Settings → Wallet
Always complete at least one full end-to-end test cycle on testnet before processing live payments. Verify that your webhook handler correctly fulfils orders, handles retries idempotently, and rejects invalid signatures.