Postman Collection

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

Download

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
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:

// 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' });

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