Configuration

Learn how to configure the ZenPays SDK for your environment.

Configuration Options

JavaScript

import { ZenPays } from '@zenxdigitalholdings/zenpays'

const zenpays = new ZenPays({
  // Required: Your API key
  apiKey: 'your-api-key',
  // here

  // Optional: API base URL (defaults to production)
  baseUrl: 'https://api.zenpays.com',

  // Optional: API version (defaults to 'v1')
  apiVersion: 'v1',

  // Optional: Request timeout in milliseconds (defaults to 30000)
  timeout: 30000,

  // Optional: Custom fetch implementation
  fetch: customFetch,
})

Python

from zenpays import ZenPays

zenpays = ZenPays(
    # Required: Your API key
    api_key="your-api-key",

    # Optional: API base URL (auto-detected from API key)
    base_url="https://api.zenpays.com",

    # Optional: Request timeout in seconds (defaults to 30)
    timeout=30,

    # Optional: HMAC secret salt for request signing
    secret_salt="your-secret-salt",
)

Environment Configuration

Production

JavaScript

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

Python

import os

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

Sandbox/Testing

JavaScript

const zenpays = new ZenPays({
  apiKey: process.env.ZENPAYS_TEST_API_KEY!,
  baseUrl: 'https://api.zenpays.com',
})

Python

import os

zenpays = ZenPays(
    api_key=os.environ["ZENPAYS_TEST_API_KEY"],
    base_url="https://api.zenpays.com",
)

Configuration Options Reference

JavaScript

Option	Type	Default	Description
apiKey	string	Required	Your ZenPays API key
baseUrl	string	'https://api.zenpays.com'	API base URL
apiVersion	string	'v1'	API version to use
timeout	number	30000	Request timeout in milliseconds
fetch	typeof fetch	globalThis.fetch	Custom fetch implementation

Python

Option	Type	Default	Description
api_key	str	Required	Your ZenPays API key
base_url	str	Auto-detected	API base URL
timeout	int	30	Request timeout in seconds
secret_salt	str	None	HMAC secret for request signing

Environment Auto-Detection:

• zp_live_* → https://api.zenpays.com
• zp_test_* → https://api.zenpays.com (sandbox; same host, routed by key)
• anything else → http://localhost:3000

Using Environment Variables

We recommend storing your API keys in environment variables:

JavaScript

# .env
ZENPAYS_API_KEY=zp_live_xxxxx
ZENPAYS_TEST_API_KEY=zp_test_xxxxx

// Use test key in development
const apiKey = process.env.NODE_ENV === 'production'
  ? process.env.ZENPAYS_API_KEY
  : process.env.ZENPAYS_TEST_API_KEY

const zenpays = new ZenPays({ apiKey: apiKey! })

Python

# .env
ZENPAYS_API_KEY=zp_live_xxxxx
ZENPAYS_TEST_API_KEY=zp_test_xxxxx

import os

# Use test key in development
api_key = (
    os.environ["ZENPAYS_API_KEY"]
    if os.getenv("ENV") == "production"
    else os.environ["ZENPAYS_TEST_API_KEY"]
)

zenpays = ZenPays(api_key=api_key)

Timeout Configuration

Adjust timeouts for different scenarios:

JavaScript

// Longer timeout for batch operations
const zenpays = new ZenPays({
  apiKey: 'your-api-key',
  timeout: 120000, // 2 minutes
})

Python

# Longer timeout for batch operations
zenpays = ZenPays(
    api_key="your-api-key",
    timeout=120,  # 2 minutes (in seconds)
)

Multiple Instances

Create multiple client instances for different environments or merchants:

JavaScript

// Production client
const prodClient = new ZenPays({
  apiKey: process.env.ZENPAYS_LIVE_KEY!,
})

// Sandbox client for testing
const testClient = new ZenPays({
  apiKey: process.env.ZENPAYS_TEST_KEY!,
  baseUrl: 'https://api.zenpays.com',
})

// Use the appropriate client based on context
const client = isTestMode ? testClient : prodClient

Python

import os

# Production client
prod_client = ZenPays(api_key=os.environ["ZENPAYS_LIVE_KEY"])

# Sandbox client for testing
test_client = ZenPays(
    api_key=os.environ["ZENPAYS_TEST_KEY"],
    base_url="https://api.zenpays.com",
)

# Use the appropriate client based on context
client = test_client if is_test_mode else prod_client

Context Manager Support

JavaScript

The JavaScript SDK doesn't require explicit cleanup, but you can implement similar patterns if needed.

Python

The Python SDK supports context managers for automatic resource cleanup:

with ZenPays(api_key="your-api-key") as zenpays:
    # Perform operations
    intent = zenpays.payments.create_payment_intent({
        "amount": 1000,
        "currency": "USD",
    })
    # HTTP session automatically closed after the block

Type Safety

JavaScript

The SDK is fully typed. Get IntelliSense and type checking:

import type { ZenPaysConfig } from '@zenxdigitalholdings/zenpays'
import { ZenPays } from '@zenxdigitalholdings/zenpays'

// Type-safe configuration
const config: ZenPaysConfig = {
  apiKey: 'your-api-key',
  timeout: 30000,
}

const zenpays = new ZenPays(config)

Python

The SDK includes comprehensive type hints for IDE support:

from zenpays import ZenPays
from zenpays.types.payment import PaymentIntent

zenpays = ZenPays(api_key="your-api-key")

# Type checkers understand the return types
intent: PaymentIntent = zenpays.payments.get_payment_intent("pi_xxx")

HMAC Request Signing

JavaScript

HMAC signing is not currently supported in the JavaScript SDK.

Python

For enhanced security, enable HMAC request signing:

zenpays = ZenPays(
    api_key="your-api-key",
    secret_salt="your-secret-salt",  # Get this from your dashboard
)

# All requests will now include an X-Signature header

This adds an HMAC-SHA256 signature to each request, providing an additional layer of security.

Next Steps

• Authentication - Learn about API key management
• Error Handling - Handle errors gracefully
• Testing - Test your integration