REST API Overview

The ZenPays REST API provides direct HTTP access to all payment processing functionality. Use this API when you need more control than the SDK provides, or when working in a language without an official SDK.

Base URL

Environment	Base URL	Description
Sandbox	https://api.zenpayz.com	Testing and development

API Versioning

All API endpoints are versioned. The current version is v1.

https://api.zenpayz.com/api/v1/{endpoint}

Request Format

All requests must:

• Use HTTPS
• Include authentication headers (see Authentication)
• Send request bodies as JSON with Content-Type: application/json

Response Format

All responses are JSON with the following structure:

Success Response

{
  "success": true,
  "data": {
    // Response data
  }
}

Error Response

{
  "success": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "The amount field is required",
    "details": {
      "field": "amount",
      "reason": "required"
    }
  }
}

HTTP Methods

Method	Usage
GET	Retrieve resources
POST	Create resources
PUT	Update resources (full replacement)
PATCH	Update resources (partial)
DELETE	Delete resources

Pagination

List endpoints support pagination with the following query parameters:

Parameter	Type	Default	Description
page	integer	1	Page number
limit	integer	20	Items per page (max 100)

Paginated responses include metadata:

{
  "success": true,
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Rate Limits

API requests are rate-limited to prevent abuse:

Environment	Limit
Production	1,000 requests/minute
Sandbox	100 requests/minute

Rate limit headers are included in all responses:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640000000

SDK vs REST API

Use Case	Recommended
Quick integration	SDK
Custom language support	REST API
Webhooks handling	REST API
Server-to-server calls	Both
Browser/client-side	SDK (handles signatures)

Quick Start

cURL

# Create a payment intent
curl -X POST https://api.zenpayz.com/api/v1/payment-intents \
  -H "Authorization: Bearer zp_test_xxxxx" \
  -H "X-Timestamp: $(date -u +%Y-%m-%dT%H:%M:%S.000Z)" \
  -H "X-Signature: your_hmac_signature" \
  -H "X-Secret-Salt: $SECRET_SALT" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "USD",
    "description": "Order #123"
  }'

JavaScript

const crypto = require('crypto');

const apiKey = process.env.ZENPAYS_API_KEY;
const secretSalt = process.env.ZENPAYS_SECRET_SALT;
const timestamp = new Date().toISOString();
const body = {
  amount: 1000,
  currency: 'USD',
  description: 'Order #123'
};

// Generate HMAC signature
const data = timestamp + JSON.stringify(body);
const signature = crypto
  .createHmac('sha256', secretSalt)
  .update(data)
  .digest('hex');

const response = await fetch('https://api.zenpayz.com/api/v1/payment-intents', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
    'X-Secret-Salt': secretSalt,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify(body),
});

const result = await response.json();
console.log(result);

Python

import hmac
import hashlib
import json
import os
from datetime import datetime
import requests

api_key = os.environ["ZENPAYS_API_KEY"]
secret_salt = os.environ["ZENPAYS_SECRET_SALT"]
timestamp = datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%S.000Z")

body = {
    "amount": 1000,
    "currency": "USD",
    "description": "Order #123"
}

# Generate HMAC signature
data = timestamp + json.dumps(body, separators=(",", ":"))
signature = hmac.new(
    secret_salt.encode(),
    data.encode(),
    hashlib.sha256
).hexdigest()

response = requests.post(
    "https://api.zenpayz.com/api/v1/payment-intents",
    headers={
        "Authorization": f"Bearer {api_key}",
        "X-Timestamp": timestamp,
        "X-Signature": signature,
        "X-Secret-Salt": secret_salt,
        "Content-Type": "application/json",
    },
    json=body,
)

print(response.json())

Next Steps

• Authentication - Learn how to authenticate requests
• Error Handling - Understand error responses
• SDK Reference - Use the SDK for easier integration