<!-- ZenPays documentation · https://docs.zenpayz.com/docs/rest-api/overview -->

# 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](/docs/rest-api/authentication))
- Send request bodies as JSON with `Content-Type: application/json`

## Response Format

All responses are JSON with the following structure:

### Success Response

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

### Error Response

```json
{
  "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:

```json
{
  "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](/docs/api-reference/client) |
| Custom language support | REST API |
| Webhooks handling | REST API |
| Server-to-server calls | Both |
| Browser/client-side | SDK (handles signatures) |

## Quick Start

<Tabs groupId="language">
  <TabItem value="curl" label="cURL" default>

```bash
# 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"
  }'
```

  </TabItem>
  <TabItem value="javascript" label="JavaScript">

```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);
```

  </TabItem>
  <TabItem value="python" label="Python">

```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())
```

  </TabItem>
</Tabs>

## Next Steps

- [Authentication](/docs/rest-api/authentication) - Learn how to authenticate requests
- [Error Handling](/docs/rest-api/errors) - Understand error responses
- [SDK Reference](/docs/api-reference/client) - Use the SDK for easier integration