Testing Your Integration

Learn how to test your ZEUSXPAY integration safely

Testing Your Integration

ZEUSXPAY provides a comprehensive testing environment so you can develop and test your integration without using real money or cryptocurrency.

Test Mode vs Live Mode

ZEUSXPAY has two separate environments:

Test Mode (Sandbox)

Use for development and testing
No real money or crypto involved
Payments auto-complete for testing
API keys start with sk_test_ or pk_test_
API endpoint: https://sandbox-api.zeusxpay.io

Live Mode (Production)

Use for real transactions
Real money and cryptocurrency
API keys start with sk_live_ or pk_live_
API endpoint: https://api.zeusxpay.io

Getting Test API Keys

Log in to your Dashboard
Toggle to Test Mode (top right)
Go to Settings → API Keys
Copy your test keys

# Test keys
ZEUSXPAY_PUBLIC_KEY=pk_test_abc123...
ZEUSXPAY_SECRET_KEY=sk_test_xyz789...

Creating Test Payments

Test payments work exactly like live payments:

const zeusxpay = new ZeusXPay('sk_test_YOUR_TEST_KEY');

const order = await zeusxpay.orders.create({
	amount: 100.0,
	currency: 'USD',
	crypto_currency: 'BTC',
	description: 'Test payment'
});

console.log('Test payment URL:', order.payment_url);

Test Payment Behavior

Automatic Completion

In test mode, payments automatically complete after 1 minute:

Create test order
Wait 60 seconds
Order status changes to completed
Webhook is sent (if configured)

Manual Completion

Force immediate completion via Dashboard:

Go to Payments in test mode
Find your test order
Click Complete Payment

Test Cryptocurrencies

Use these test addresses for manual testing:

BTC (Bitcoin):
bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh

ETH (Ethereum):
0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

USDT (ERC-20):
0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb

Testing Different Scenarios

Successful Payment

// Create order
const order = await zeusxpay.orders.create({
	amount: 100.0,
	currency: 'USD',
	crypto_currency: 'BTC'
});

// Wait 60 seconds or complete manually
// Order will become 'completed'

Failed Payment

// Create order with very short expiration
const order = await zeusxpay.orders.create({
	amount: 100.0,
	currency: 'USD',
	crypto_currency: 'BTC',
	expires_in: 60 // 1 minute
});

// Wait for expiration
// Order will become 'expired'

Partial Payment

// In test mode, you can simulate partial payments
// via the Dashboard "Simulate Payment" tool

Underpayment

// Test handling of underpayments
// Use Dashboard to simulate sending less crypto than required

Testing Webhooks

Local Development

Use ngrok to receive webhooks locally:

# Install ngrok
npm install -g ngrok

# Start your local server
npm run dev

# Expose your server
ngrok http 3000

# Update webhook URL in Dashboard
https://abc123.ngrok.io/webhooks/zeusxpay

Webhook Logs

View webhook delivery logs in Dashboard:

Go to Settings → Webhooks
Select your webhook endpoint
View Recent Deliveries
See request/response details

Send Test Webhooks

Trigger test webhooks manually:

Go to Settings → Webhooks
Click Send Test Event
Select event type
Click Send

Verify Signatures

Test signature verification:

const crypto = require('crypto');

function testWebhookSignature() {
	const payload = JSON.stringify({
		id: 'evt_test_123',
		type: 'order.completed',
		data: { id: 'ord_test_123' }
	});

	const signature = crypto
		.createHmac('sha256', process.env.WEBHOOK_SECRET)
		.update(payload)
		.digest('hex');

	// Test your verification function
	const isValid = verifyWebhook(payload, signature, process.env.WEBHOOK_SECRET);
	console.log('Signature valid:', isValid);
}

Testing API Endpoints

Use the API Playground

Test API calls interactively:

Visit API Playground
Enter your test API key
Select an endpoint
Customize parameters
Click “Try it”

cURL Commands

Test with cURL:

# Create order
curl -X POST https://sandbox-api.zeusxpay.io/v1/orders 
  -H "Authorization: Bearer sk_test_YOUR_KEY" 
  -H "Content-Type: application/json" 
  -d '{
    "amount": 100.00,
    "currency": "USD",
    "crypto_currency": "BTC"
  }'

# Get order
curl https://sandbox-api.zeusxpay.io/v1/orders/ord_test_123 
  -H "Authorization: Bearer sk_test_YOUR_KEY"

# List orders
curl https://sandbox-api.zeusxpay.io/v1/orders 
  -H "Authorization: Bearer sk_test_YOUR_KEY"

Test Data

Test Cards (for fiat on-ramps)

Success: 4242 4242 4242 4242
Decline: 4000 0000 0000 0002
Expired: 4000 0000 0000 0069

Test Email Addresses

success@zeusxpay.io - Always succeeds
fail@zeusxpay.io - Always fails
slow@zeusxpay.io - Takes 2 minutes to complete

Testing Error Handling

Test Different Error Scenarios

// Invalid API key
try {
  const zeusxpay = new ZeusXPay('sk_invalid_key');
  await zeusxpay.orders.create({ ... });
} catch (error) {
  console.log('Auth error:', error.message);
}

// Invalid amount
try {
  await zeusxpay.orders.create({
    amount: -10, // Invalid
    currency: 'USD'
  });
} catch (error) {
  console.log('Validation error:', error.message);
}

// Network error
try {
  // Simulate network timeout
  await zeusxpay.orders.create(
    { ... },
    { timeout: 1 } // 1ms timeout
  );
} catch (error) {
  console.log('Network error:', error.message);
}

Handle Rate Limits

// Test rate limiting behavior
async function testRateLimit() {
	const promises = [];

	// Send 200 requests quickly
	for (let i = 0; i < 200; i++) {
		promises.push(zeusxpay.orders.list().catch((e) => e));
	}

	const results = await Promise.all(promises);
	const rateLimited = results.filter((r) => r.status === 429);

	console.log(`Rate limited: ${rateLimited.length}/200`);
}

Automated Testing

Unit Tests

// Jest example
describe('ZEUSXPAY Integration', () => {
  let zeusxpay;

  beforeAll(() => {
    zeusxpay = new ZeusXPay(process.env.ZEUSXPAY_TEST_KEY);
  });

  test('creates order successfully', async () => {
    const order = await zeusxpay.orders.create({
      amount: 100.00,
      currency: 'USD',
      crypto_currency: 'BTC'
    });

    expect(order.id).toBeTruthy();
    expect(order.status).toBe('pending');
    expect(order.amount).toBe(100.00);
  });

  test('retrieves order by ID', async () => {
    const created = await zeusxpay.orders.create({ ... });
    const retrieved = await zeusxpay.orders.retrieve(created.id);

    expect(retrieved.id).toBe(created.id);
  });

  test('handles invalid API key', async () => {
    const invalid = new ZeusXPay('sk_invalid');

    await expect(
      invalid.orders.list()
    ).rejects.toThrow('Invalid API key');
  });
});

Integration Tests

// Test full payment flow
describe('Payment Flow', () => {
	test('complete payment flow', async () => {
		// 1. Create order
		const order = await createOrder();
		expect(order.status).toBe('pending');

		// 2. Complete payment (in test mode)
		await completeTestPayment(order.id);

		// 3. Verify webhook received
		const webhook = await waitForWebhook(order.id);
		expect(webhook.type).toBe('order.completed');

		// 4. Verify order status updated
		const updated = await zeusxpay.orders.retrieve(order.id);
		expect(updated.status).toBe('completed');
	});
});

Pre-Production Checklist

Before going live, verify:

Going Live

When ready to go live:

Get live API keys from Dashboard

Update environment variables:

ZEUSXPAY_SECRET_KEY=sk_live_YOUR_LIVE_KEY
ZEUSXPAY_PUBLIC_KEY=pk_live_YOUR_LIVE_KEY

Update API endpoint to https://api.zeusxpay.io
Register live webhook URL
Enable live mode in your application
Monitor first transactions closely

Testing Tools

API Playground: /docs/api-playground
Webhook Tester: https://zeusxpay.io/tools/webhook-tester
Request Logger: View in Dashboard
Postman Collection: https://zeusxpay.io/postman

Common Testing Issues

Webhooks Not Received

Check ngrok is running
Verify webhook URL is correct
Check server logs for errors
Ensure endpoint returns 200

Payments Don’t Complete

Wait full 60 seconds in test mode
Or use “Complete Payment” in Dashboard
Check order hasn’t expired

Signature Verification Fails

Use raw request body
Check webhook secret is correct
Verify header name is exact