List Transactions

Retrieve a paginated list of transactions with optional filters.

GEThttps://api.zenpayz.com/api/v1/transactions

Bearer · API key

Request

Headers

Header	Description
Authorization REQUIRED	Bearer {api_key}
X-Signature REQUIRED	HMAC-SHA256 signature
X-Timestamp REQUIRED	ISO 8601 timestamp
X-Secret-Salt REQUIRED	Secret salt for HMAC validation

Query Parameters

Parameter	Type	Description
page OPTIONAL	integer1	Page number
limit OPTIONAL	integer20	Items per page (max 100)
status OPTIONAL	string-	Filter by status
paymentMethod OPTIONAL	string-	Filter by payment method
currency OPTIONAL	string-	Filter by currency code
customerId OPTIONAL	string-	Filter by customer ID
transactionId OPTIONAL	string-	Filter by transaction ID
minAmount OPTIONAL	integer-	Minimum amount
maxAmount OPTIONAL	integer-	Maximum amount
startDate OPTIONAL	string-	Start date (ISO 8601)
endDate OPTIONAL	string-	End date (ISO 8601)
search OPTIONAL	string-	Search in ID, email, name

Transaction Status Values

Status	Description
initiated	Transaction created
processing	Being processed
success	Completed successfully
failed	Transaction failed
cancelled	Cancelled by user/merchant
refunded	Full refund processed
partially_refunded	Partial refund processed

Response

Success (200 OK)

{
  "success": true,
  "data": [
    {
      "id": "txn_xxxxx",
      "intentId": "pi_xxxxx",
      "merchantId": "mer_xxxxx",
      "customerId": "cus_xxxxx",
      "customerName": "John Doe",
      "customerEmail": "john@example.com",
      "amount": 1000,
      "currency": "USD",
      "status": "success",
      "paymentMethod": "upi",
      "processingFee": 29,
      "netAmount": 971,
      "metadata": {
        "orderId": "order_123"
      },
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:35:00.000Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 150,
    "totalPages": 8
  }
}

Error Responses

Code	HTTP	Message
INVALID_REQUEST	400	Invalid query parameters
UNAUTHORIZED	401	Invalid API key

Examples

cURL

curl -X GET "https://api.zenpayz.com/api/v1/transactions?status=success&limit=50&startDate=2024-01-01" \
  -H "Authorization: Bearer zp_test_xxxxx" \
  -H "X-Timestamp: 2024-01-15T10:30:00.000Z" \
  -H "X-Signature: a1b2c3d4e5f6..." \
  -H "X-Secret-Salt: your_secret_salt"

JavaScript

const crypto = require('crypto');

const apiKey = process.env.ZENPAYS_API_KEY;
const secretSalt = process.env.ZENPAYS_SECRET_SALT;
const timestamp = new Date().toISOString();

// For GET requests, use empty object
const signature = crypto
  .createHmac('sha256', secretSalt)
  .update(timestamp + '{}')
  .digest('hex');

const params = new URLSearchParams({
  status: 'success',
  limit: '50',
  startDate: '2024-01-01',
});

const response = await fetch(
  `https://api.zenpayz.com/api/v1/transactions?${params}`,
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'X-Timestamp': timestamp,
      'X-Signature': signature,
      'X-Secret-Salt': secretSalt,
    },
  }
);

const result = await response.json();
console.log(`Found ${result.pagination.total} transactions`);
result.data.forEach(txn => {
  console.log(`${txn.id}: ${txn.amount} ${txn.currency} - ${txn.status}`);
});

Python

import hmac
import hashlib
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")

# For GET requests, use empty object
data = timestamp + "{}"
signature = hmac.new(
    secret_salt.encode(),
    data.encode(),
    hashlib.sha256
).hexdigest()

response = requests.get(
    "https://api.zenpayz.com/api/v1/transactions",
    headers={
        "Authorization": f"Bearer {api_key}",
        "X-Timestamp": timestamp,
        "X-Signature": signature,
        "X-Secret-Salt": secret_salt,
    },
    params={
        "status": "success",
        "limit": 50,
        "startDate": "2024-01-01",
    },
)

result = response.json()
print(f"Found {result['pagination']['total']} transactions")
for txn in result["data"]:
    print(f"{txn['id']}: {txn['amount']} {txn['currency']} - {txn['status']}")

SDK (Recommended)

// JavaScript SDK - handles authentication automatically
const { data, total } = await zenpays.payments.listTransactions({
  status: 'success',
  limit: 50,
  from: '2024-01-01',
});

console.log(`Found ${total} transactions`);
data.forEach(txn => {
  console.log(`${txn.id}: ${txn.amount} ${txn.currency} - ${txn.status}`);
});

Filtering Examples

By Date Range

GET /api/v1/transactions?startDate=2024-01-01&endDate=2024-01-31

By Amount Range

GET /api/v1/transactions?minAmount=1000&maxAmount=10000

By Customer

GET /api/v1/transactions?customerId=cus_xxxxx

Combined Filters

GET /api/v1/transactions?status=success&currency=USD&paymentMethod=upi&limit=100

Related Endpoints

• Get Transaction
• Export Transactions