Client

The ZenPays client is the main entry point for the SDK.

Constructor

JavaScript

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

JavaScript

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.

JavaScript

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

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:

import { constructWebhookEvent, verifyWebhookSignature } from '@zenxdigitalholdings/zenpays'

See the signature verification guide.

Example

JavaScript

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

JavaScript doesn't require explicit resource cleanup.

Python

The Python SDK supports context managers for automatic cleanup:

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:

JavaScript

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 for more details.