Docs/Testing

Testing

Test your integration without processing real payments. Use test mode API keys and test card numbers.

Test Mode vs Live Mode

Feature	Test Mode	Live Mode
API Key Prefix	wp3_test_sk_	wp3_live_sk_
Real Payments	No	Yes
Crypto Delivery	Simulated	Real
Webhooks	Sent normally	Sent normally
Dashboard	Separate test data	Separate live data

Toggle between test and live mode in your dashboard to view respective data.

Test Card Numbers

Use these card numbers in test mode. Use any future expiry date and any 3-digit CVC.

Successful Payments

Card Number	Brand	Result
4242 4242 4242 4242	Visa	Succeeds
4000 0566 5566 5556	Visa (debit)	Succeeds
5555 5555 5555 4444	Mastercard	Succeeds
3782 822463 10005	American Express	Succeeds

Declined Payments

Card Number	Decline Reason
4000 0000 0000 0002	Generic decline
4000 0000 0000 9995	Insufficient funds
4000 0000 0000 9987	Lost card
4000 0000 0000 0069	Expired card
4000 0000 0000 0127	Incorrect CVC

3D Secure Authentication

Card Number	Behavior
4000 0027 6000 3184	Requires authentication, succeeds
4000 0082 6000 3178	Requires authentication, fails

Test Wallet Addresses

In test mode, you can use any valid wallet address. No real crypto will be sent. Here are some valid test addresses:

# Ethereum/EVM compatible
0x742d35Cc6634C0532925a3b844Bc9e7595f5fB
0x8ba1f109551bD432803012645Hac136c22C5Bc
0x1234567890123456789012345678901234567890

# The "zero address" (not recommended)
0x0000000000000000000000000000000000000000

Local Webhook Testing

To receive webhooks locally during development, use a tunnel service like ngrok:

bash

# Start your local server
-green-400">npm run dev

# In another terminal, start ngrok
-green-400">ngrok http 3000

# You'll get a URL like: https://abc123.ngrok.io
# Add this URL as your webhook endpoint in the dashboard:
# https://abc123.ngrok.io/api/webhooks/web3pay

Alternative Tunneling Services

ngrok - Most popular, free tier available
localtunnel - Free and open source
Tailscale Funnel - Part of Tailscale VPN

Simulating Webhook Events

You can trigger test webhooks from the dashboard, or manually send test events:

bash

# Simulate a completed transaction webhook
-green-400">curl -X POST http://localhost:3000/api/webhooks/web3pay \
  -H "Content-Type: application/json" \
  -H "x-web3pay-signature: t=1732624500,v1=test_signature" \
  -d '{
    "id": "evt_test_123",
    "type": "onramp.session.completed",
    "created_at": "2024-01-15T12:08:00Z",
    "data": {
      "session_id": "onramp_sess_test",
      "status": "completed",
      "wallet_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f5fB",
      "crypto_amount": "0.0412",
      "tx_hash": "0xtest123..."
    }
  }'

Note: In development, you may want to skip signature verification or use a known test secret.

Testing Checklist

Before going live, verify these scenarios work correctly:

Happy Path

Create a session successfully
Complete payment with test card 4242...
Receive completed webhook
Verify transaction appears in dashboard

Payment Failures

Test declined card (4000 0000 0000 0002)
Test insufficient funds (4000 0000 0000 9995)
Verify failed webhook is received
Verify error message shown to user

Edge Cases

Session expiry (wait 30+ minutes)
Invalid wallet address
Amount below minimum ($10)
Unsupported currency/network

Webhooks

Signature verification works
Duplicate events handled (idempotency)
Failed webhook triggers retry

Going Live

When you're ready to accept real payments:

Complete Stripe Connect verification in the dashboard
Generate live API keys (wp3_live_sk_...)
Update your application to use live keys
Update webhook URL to point to production
Test with a small real transaction

Keep environments separate

Never use test API keys in production or live keys in development. Keep your keys in environment variables and use different values per environment.