<!-- ZenPays documentation · https://docs.zenpayz.com/docs/resources/postman-collection -->

---
sidebar_position: 1
title: Postman Collection
description: Pre-configured Postman collection for testing ZenPays API endpoints
---

# Postman Collection

Test and explore the ZenPays API using our pre-configured Postman collection with 60+ API endpoints across 10 categories.

## Download

export const DownloadButton = () => {
  const handleDownload = () => {
    const link = document.createElement('a');
    link.href = '/downloads/zenpay-merchant-service.postman_collection.json';
    link.download = 'zenpay-merchant-service.postman_collection.json';
    document.body.appendChild(link);
    link.click();
    document.body.removeChild(link);
  };
  return (
    <button
      onClick={handleDownload}
      className="inline-block px-5 py-2.5 bg-green-600 hover:bg-green-700 text-white rounded-md no-underline text-base font-medium cursor-pointer border-none"
    >
      Download Postman Collection
    </button>
  );
};

<DownloadButton />

## Features

- **60+ Pre-configured Endpoints** - All API endpoints ready to use
- **Auto HMAC Signing** - Pre-request script auto-generates `X-Signature` and `X-Timestamp` headers
- **Example Request Bodies** - Realistic sample data for every endpoint
- **Environment Variables** - Easy switching between sandbox and production
- **Optional Query Params** - Disabled filters you can toggle on as needed

## Included Endpoints

| Category | Endpoints | Description |
|----------|-----------|-------------|
| Payment Intents | 3 | Create, get, and confirm payments |
| Transactions | 4 | List, search, and export |
| Customers | 7 | Create, update, risk, top customers |
| Payouts | 8 | Create, preview, retry, stats, export |
| Refunds | 5 | Create, list, cancel, stats |
| Settlements | 9 | Create, cancel, bank accounts management |
| Wallet | 4 | Balances, transactions, summary |
| Ledger | 8 | Entries, balances, reserves, reconciliation |
| Reports | 5 | Generate, list, download, delete |
| Health | 1 | Health check |

## Quick Start

1. **Download** the collection using the button above
2. **Open Postman** and click "Import"
3. **Select** the downloaded JSON file
4. **Set variables**: `apiKey` and `secretSalt` from your [ZenPays Dashboard](https://dashboard.zenpays.com)
5. **Start testing** - signatures are generated automatically!

## Collection Variables

| Variable | Description |
|----------|-------------|
| `baseUrl` | API base URL (default: `https://api.zenpayz.com`) |
| `apiKey` | Your API key (e.g., `zp_test_xxxxx` or `zp_live_xxxxx`) |
| `secretSalt` | Your secret salt for HMAC signature generation |

## Authentication

All requests use **API Key + HMAC Signature** authentication. The collection includes a **pre-request script** that automatically generates all required headers before every request — you just need to set your credentials once.

### Required Headers (auto-generated)

Every request sends these 5 headers, all handled automatically by the pre-request script:

| Header | Value | Description |
|--------|-------|-------------|
| `Authorization` | `Bearer {apiKey}` | Your API key from the collection variables |
| `X-Timestamp` | ISO 8601 UTC timestamp | Generated at request time (e.g., `2024-01-15T10:30:00.000Z`) |
| `X-Signature` | HMAC-SHA256 hex string | Computed from timestamp + body using your secret salt |
| `X-Secret-Salt` | Your secret salt | Passed for server-side HMAC validation |
| `Content-Type` | `application/json` | Set on all requests |

### How the Pre-Request Script Works

The collection's pre-request script runs before every request and does the following:

```javascript
// 1. Reads your credentials from collection variables
const apiKey = pm.collectionVariables.get('apiKey');
const secretSalt = pm.collectionVariables.get('secretSalt');

// 2. Generates a fresh timestamp
const timestamp = new Date().toISOString();

// 3. Compacts the request body (strips whitespace/newlines)
//    For GET requests or empty bodies, uses '{}'
const body = pm.request.body?.raw
  ? JSON.stringify(JSON.parse(pm.request.body.raw))
  : '{}';

// 4. Computes HMAC-SHA256 signature
const signature = CryptoJS.HmacSHA256(timestamp + body, secretSalt).toString();

// 5. Sets all required headers automatically
pm.request.headers.upsert({ key: 'Authorization', value: 'Bearer ' + apiKey });
pm.request.headers.upsert({ key: 'X-Timestamp', value: timestamp });
pm.request.headers.upsert({ key: 'X-Signature', value: signature });
pm.request.headers.upsert({ key: 'X-Secret-Salt', value: secretSalt });
pm.request.headers.upsert({ key: 'Content-Type', value: 'application/json' });
```

:::caution Important
The `apiKey` collection variable should contain **only** the key itself (e.g., `zp_test_abc123`), **not** the `Bearer` prefix. The script adds `Bearer ` automatically.
:::

## Environment Setup

### Option 1: Collection Variables (Recommended)

After importing, set the variables directly in the collection:

1. Click the collection name **"ZenPays API"** in the sidebar
2. Go to the **Variables** tab
3. Set these values in the **Current Value** column:

| Variable | Current Value |
|----------|---------------|
| `baseUrl` | `https://api.zenpayz.com` |
| `apiKey` | `zp_test_your_key_here` |
| `secretSalt` | `your_secret_salt_here` |

4. Click **Save**

### Option 2: Postman Environments

Create a Postman Environment for each stage:

1. Click the **Environments** tab (gear icon) in the sidebar
2. Click **+** to create a new environment
3. Name it (e.g., "ZenPays Sandbox")
4. Add the same 3 variables: `baseUrl`, `apiKey`, `secretSalt`
5. Select the environment from the dropdown in the top-right corner

:::tip
If you use **both** environment variables and collection variables, environment variables take priority. Make sure to clear any environment overrides if you want the collection variables to be used.
:::

### Environments

| Environment | Base URL |
|-------------|----------|
| **Sandbox** | `https://api.zenpayz.com` |

## Troubleshooting

| Issue | Cause | Fix |
|-------|-------|-----|
| `401 Missing Authorization header` | Pre-request script not running | Re-import the collection; ensure `apiKey` and `secretSalt` are set |
| `401 Invalid HMAC signature` | Body format mismatch or wrong secret salt | Verify `secretSalt` is correct; check Postman Console for sent headers |
| `Bearer Bearer zp_test_...` in logs | `apiKey` variable includes `Bearer ` prefix | Remove `Bearer ` from the `apiKey` value — the script adds it |
| Headers not appearing on request | Environment variable overrides with empty values | Clear or delete environment variable overrides |
| `Request timestamp expired` | System clock drift or stale request | Ensure your system clock is accurate; the signature expires after 5 minutes |

## Tips

- **View Console** - Use Postman Console (**View → Show Postman Console**) to see the exact headers being sent and debug authentication issues
- **Toggle filters** - Many GET endpoints have optional query parameters (disabled by default) — enable the ones you need
- **Idempotency** - POST endpoints include `X-Idempotency-Key` headers to prevent duplicate requests
- **Use environments** - Create separate Postman environments for sandbox vs production to avoid accidental production calls