# Client
The `ZenPays` client is the main entry point for the SDK.
## Constructor
```typescript
import { ZenPays } from '@zenxdigitalholdings/zenpays'
const zenpays = new ZenPays(config: ZenPaysConfig)
```
```python
from zenpays import ZenPays
zenpays = ZenPays(**config)
```
## Configuration
### JavaScript
| Property | Type | Required | Default | Description |
|----------|------|----------|---------|-------------|
| `apiKey` | `string` | Yes | - | Your ZenPays API key |
| `baseUrl` | `string` | No | `'https://api.zenpayz.com'` | API base URL |
| `apiVersion` | `string` | No | `'v1'` | API version |
| `timeout` | `number` | No | `30000` | Request timeout in ms |
| `fetch` | `typeof fetch` | No | `globalThis.fetch` | Custom fetch function |
### Python
| Property | Type | Required | Default | Description |
|----------|------|----------|---------|-------------|
| `api_key` | `str` | Yes | - | Your ZenPays API key |
| `base_url` | `str` | No | Auto-detected | API base URL |
| `timeout` | `int` | No | `30` | Request timeout in seconds |
| `secret_salt` | `str` | No | `None` | HMAC secret for request signing |
## Factory Function
```typescript
import { createClient } from '@zenxdigitalholdings/zenpays'
const zenpays = createClient({
apiKey: 'your-api-key',
})
```
```python
from zenpays import ZenPays
# Direct initialization (recommended)
zenpays = ZenPays(api_key="your-api-key")
```
## Properties
### version
Returns the SDK version.
```typescript
console.log(zenpays.version) // '0.5.0'
```
```python
from zenpays import __version__
print(__version__) # '0.1.1'
```
## API Modules
The client provides access to all API modules:
| Property | Type | Description |
|----------|------|-------------|
| `analytics` | `AnalyticsApi` | Reporting and aggregate metrics |
| `auth` | `AuthApi` | API key and session operations |
| `chargebacks` | `ChargebacksApi` | Disputes and evidence submission |
| `checkout` | `CheckoutApi` | Checkout sessions and on-ramp |
| `customers` | `CustomersApi` | Customer management |
| `invoices` | `InvoicesApi` | Invoice creation and delivery |
| `ledger` | `LedgerApi` | Double-entry ledger and reconciliation |
| `merchants` | `MerchantsApi` | Webhooks, bank accounts, IP whitelist |
| `offRamp` | `OffRampApi` | Crypto-to-fiat conversion |
| `paymentLinks` | `PaymentLinksApi` | Shareable payment links |
| `payments` | `PaymentsApi` | Payment intents and transactions |
| `payoutIntents` | *(object)* | Payout-intent shorthands — see below |
| `payouts` | `PayoutsApi` | Payout operations |
| `rampIntents` | `RampIntentsApi` | On/off-ramp intent lifecycle |
| `refunds` | `RefundsApi` | Refund operations |
| `security` | `SecurityApi` | 2FA and security settings |
| `settlements` | `SettlementsApi` | Settlement management |
| `subscriptions` | `SubscriptionsApi` | Plans, stored methods, recurring billing |
| `tenantHostnames` | `TenantHostnamesApi` | White-label hostname mapping |
| `vendors` | `VendorsApi` | Vendor accounts, commissions, referrals |
| `wallet` | `WalletApi` | Wallet balance and transactions |
:::note Python parity
The Python SDK currently implements `analytics`, `checkout`, `customers`, `merchants`, `payments`, `payouts`, `refunds`, `security`, `settlements`, and `wallet`. The remaining namespaces are JavaScript-only — call the REST endpoints directly from Python.
:::
### payoutIntents
`payoutIntents` is a convenience object, not an API class. Each property forwards to the correspondingly named method on `payouts`:
| Property | Forwards to |
|----------|-------------|
| `payoutIntents.create` | `payouts.createPayoutIntent` |
| `payoutIntents.confirm` | `payouts.confirmPayoutIntent` |
| `payoutIntents.get` | `payouts.getPayoutIntent` |
| `payoutIntents.list` | `payouts.listPayoutIntents` |
| `payoutIntents.cancel` | `payouts.cancelPayoutIntent` |
## Webhook Helpers
Signature verification is exported at the package root rather than hung off the client, so it can run in a webhook route with no API key present:
```typescript
import { constructWebhookEvent, verifyWebhookSignature } from '@zenxdigitalholdings/zenpays'
```
See the [signature verification guide](/docs/guides/webhooks/signature-verification).
## Example
```typescript
import { ZenPays } from '@zenxdigitalholdings/zenpays'
const zenpays = new ZenPays({
apiKey: process.env.ZENPAYS_API_KEY!,
})
// Use any API module
const balance = await zenpays.wallet.getBalance()
const customers = await zenpays.customers.list()
```
```python
import os
from zenpays import ZenPays
zenpays = ZenPays(api_key=os.environ["ZENPAYS_API_KEY"])
# Use any API module
balance = zenpays.wallet.get_balance()
customers = zenpays.customers.list()
```
## Context Manager
JavaScript doesn't require explicit resource cleanup.
The Python SDK supports context managers for automatic cleanup:
```python
with ZenPays(api_key="your-api-key") as zenpays:
balance = zenpays.wallet.get_balance()
# HTTP session automatically closed after the block
```
## Error Handling
All API methods throw typed errors:
```typescript
import {
AuthenticationError,
AuthorizationError,
ConfigurationError,
NetworkError,
NotFoundError,
PaymentError,
RateLimitError,
ValidationError,
ZenPaysError,
} from '@zenxdigitalholdings/zenpays'
try {
await zenpays.payments.getPaymentIntent('invalid-id')
}
catch (error) {
if (error instanceof NotFoundError) {
console.log('Payment intent not found')
}
else if (error instanceof AuthenticationError) {
console.log('Invalid API key')
}
}
```
```python
from zenpays.errors import (
AuthenticationError,
PermissionError,
NetworkError,
ResourceNotFoundError,
PaymentError,
RateLimitError,
ValidationError,
ZenPaysError,
)
try:
zenpays.payments.get_payment_intent("invalid-id")
except ResourceNotFoundError:
print("Payment intent not found")
except AuthenticationError:
print("Invalid API key")
```
See the [Error Handling guide](/docs/guides/error-handling) for more details.