Authentication

Learn how to manage API keys and authenticate with the ZenPays API.

API Key Types

ZenPays uses two types of API keys:

Key Type	Prefix	Usage
Live	zp_live_	Production payments
Test	zp_test_	Sandbox testing

Getting Your API Key

1. Log in to your ZenPays Dashboard
2. Navigate to Settings → API Keys
3. Copy your API key

warning

Keep your API keys secure. Never expose them in client-side code or commit them to version control.

Using the SDK

JavaScript

import { ZenPays } from '@zenxdigitalholdings/zenpays'

const zenpays = new ZenPays({
  apiKey: process.env.ZENPAYS_API_KEY!,
})

Python

import os
from zenpays import ZenPays

zenpays = ZenPays(api_key=os.environ["ZENPAYS_API_KEY"])

Environment-Based Authentication

JavaScript

// Determine environment from API key prefix
function getEnvironment(apiKey: string): 'live' | 'test' {
  return apiKey.startsWith('zp_live_') ? 'live' : 'test'
}

const zenpays = new ZenPays({
  apiKey: process.env.ZENPAYS_API_KEY!,
})

console.log('Environment:', getEnvironment(process.env.ZENPAYS_API_KEY!))

Python

import os

# Determine environment from API key prefix
def get_environment(api_key: str) -> str:
    if api_key.startswith("zp_live_"):
        return "live"
    elif api_key.startswith("zp_test_"):
        return "test"
    return "dev"

zenpays = ZenPays(api_key=os.environ["ZENPAYS_API_KEY"])

print(f"Environment: {get_environment(os.environ['ZENPAYS_API_KEY'])}")

IP Whitelisting

For enhanced security, whitelist IPs allowed to use your API keys:

JavaScript

// List whitelisted IPs
const ips = await zenpays.merchants.listWhitelistedIPs()

// Add a new IP
await zenpays.merchants.addIPToWhitelist(
  '203.0.113.50',
  'Production Server'
)

// Remove an IP
await zenpays.merchants.removeIPFromWhitelist('ip_entry_id')

Python

# List whitelisted IPs
ips = zenpays.merchants.list_whitelisted_ips()

# Add a new IP
zenpays.merchants.add_ip_to_whitelist(
    "203.0.113.50",
    "Production Server"
)

# Remove an IP
zenpays.merchants.remove_ip_from_whitelist("ip_entry_id")

Two-Factor Authentication

Enable 2FA for additional security:

JavaScript

// Setup 2FA
const setup = await zenpays.security.setup2FA()
console.log('Scan this QR code:', setup.qrCodeUrl)
console.log('Backup codes:', setup.backupCodes)

// Verify 2FA code
await zenpays.security.verify2FA({ code: '123456' })

// Check 2FA status
const status = await zenpays.security.is2FAEnabled()
console.log('2FA enabled:', status.enabled)

Python

# Setup 2FA
setup = zenpays.security.setup_two_factor()
print(f"Scan this QR code: {setup['qr_code_url']}")
print(f"Backup codes: {setup['backup_codes']}")

# Verify 2FA code
zenpays.security.verify_two_factor({"code": "123456"})

# Check 2FA status
status = zenpays.security.is_two_factor_enabled()
print(f"2FA enabled: {status['enabled']}")

Best Practices

1. Use environment variables - Never hardcode API keys
2. Rotate keys regularly - Create new keys and revoke old ones
3. Use minimal scopes - Only grant necessary permissions
4. Enable IP whitelisting - Restrict access to known IPs
5. Enable 2FA - Add an extra layer of security
6. Monitor usage - Check API key usage in the dashboard

Handling Authentication Errors

JavaScript

import { AuthenticationError, AuthorizationError } from '@zenxdigitalholdings/zenpays'

try {
  await zenpays.payments.createPaymentIntent({
    amount: 1000,
    currency: 'USD',
  })
}
catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key')
  }
  else if (error instanceof AuthorizationError) {
    console.error('API key lacks required permissions')
  }
}

Python

from zenpays.errors import AuthenticationError, PermissionError

try:
    zenpays.payments.create_payment_intent({
        "amount": 1000,
        "currency": "USD",
    })
except AuthenticationError:
    print("Invalid API key")
except PermissionError:
    print("API key lacks required permissions")

Next Steps

• Quick Start - Create your first payment
• Security Guide - Learn more about security best practices
• Webhooks - Verify webhook signatures