# Configuration
Learn how to configure the ZenPays SDK for your environment.
## Configuration Options
```typescript
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.zenpayz.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.zenpayz.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
```typescript
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
```typescript
const zenpays = new ZenPays({
apiKey: process.env.ZENPAYS_TEST_API_KEY!,
baseUrl: 'https://sandbox.zenpays.com',
})
```
```python
import os
zenpays = ZenPays(
api_key=os.environ["ZENPAYS_TEST_API_KEY"],
base_url="https://sandbox.zenpays.com",
)
```
## Configuration Options Reference
### JavaScript
| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `apiKey` | `string` | *Required* | Your ZenPays API key |
| `baseUrl` | `string` | `'https://api.zenpayz.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.zenpayz.com`
- `zp_test_*` โ `https://api.test.zenpays.com`
- `zp_dev_*` โ `https://api.dev.zenpays.com`
## Using Environment Variables
We recommend storing your API keys in environment variables:
```bash
# .env
ZENPAYS_API_KEY=zp_live_xxxxx
ZENPAYS_TEST_API_KEY=zp_test_xxxxx
```
```typescript
// 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! })
```
```bash
# .env
ZENPAYS_API_KEY=zp_live_xxxxx
ZENPAYS_TEST_API_KEY=zp_test_xxxxx
```
```python
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:
```typescript
// 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:
```typescript
// 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://sandbox.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://sandbox.zenpays.com",
)
# Use the appropriate client based on context
client = test_client if is_test_mode else prod_client
```
## Context Manager Support
The JavaScript SDK doesn't require explicit cleanup, but you can implement similar patterns if needed.
The Python SDK supports context managers for automatic resource cleanup:
```python
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
The SDK is fully typed. Get IntelliSense and type checking:
```typescript
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)
```
The SDK includes comprehensive type hints for IDE support:
```python
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
HMAC signing is not currently supported in the JavaScript SDK.
For enhanced security, enable HMAC request signing:
```python
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](/docs/getting-started/authentication) - Learn about API key management
- [Error Handling](/docs/guides/error-handling) - Handle errors gracefully
- [Testing](/docs/guides/testing) - Test your integration