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

import { ZenPays } from 'zenpays'

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

Managing API Keys

List API Keys

const keys = await zenpays.merchants.listApiKeys()

keys.forEach((key) => {
  console.log(`${key.name}: ${key.keyPrefix}*** (${key.environment})`)
})

Create a New API Key

const newKey = await zenpays.merchants.createApiKey({
  name: 'Mobile App Key',
  environment: 'production',
  scopes: ['payments:write', 'refunds:write'],
  expiresIn: 365 * 24 * 60 * 60 * 1000, // 1 year in ms
})

// Store the key securely - it's only shown once!
console.log('New API Key:', newKey.key)

Revoke an API Key

await zenpays.merchants.revokeApiKey('key_id_to_revoke')

API Key Scopes

Control what each API key can access:

Scope	Description
payments:read	Read payment intents and transactions
payments:write	Create and manage payments
refunds:read	Read refund information
refunds:write	Create and manage refunds
payouts:read	Read payout information
payouts:write	Create and manage payouts
customers:read	Read customer data
customers:write	Create and manage customers
webhooks:manage	Create and manage webhooks
analytics:read	Access analytics data

Environment-Based Authentication

// 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!))

IP Whitelisting

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

// 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')

Two-Factor Authentication

Enable 2FA for additional security:

// 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)

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

import { AuthenticationError, AuthorizationError } from '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')
  }
}

Next Steps

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