List Vendors

Retrieve a paginated list of vendors with support for filtering, searching, and sorting.

GEThttps://api.zenpayz.com/merchant/api/v1/vendors

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
Content-Type REQUIRED	application/json

Query Parameters

Parameter	Type	Description
name OPTIONAL	string	Filter by vendor name (partial match)
email OPTIONAL	string	Filter by vendor email
vendorId OPTIONAL	string	Filter by vendor ID
status OPTIONAL	string	Filter by status (active, inactive, suspended, pending)
riskLevel OPTIONAL	string	Filter by risk level (low, medium, high, critical)
environment OPTIONAL	string	Filter by environment
commissionType OPTIONAL	string	Filter by commission type (percentage, fixed, tiered)
minCommissionRate OPTIONAL	number	Minimum commission rate
maxCommissionRate OPTIONAL	number	Maximum commission rate
minTotalReferrals OPTIONAL	number	Minimum total referrals count
minActiveReferrals OPTIONAL	number	Minimum active referrals count
minCommissionEarned OPTIONAL	number	Minimum total commission earned
payoutFrequency OPTIONAL	string	Filter by payout frequency (weekly, monthly, quarterly)
kycStatus OPTIONAL	string	Filter by KYC verification status
createdAfter OPTIONAL	string	Filter vendors created after this date (ISO 8601)
createdBefore OPTIONAL	string	Filter vendors created before this date (ISO 8601)
lastPayoutAfter OPTIONAL	string	Filter by last payout date (after, ISO 8601)
lastPayoutBefore OPTIONAL	string	Filter by last payout date (before, ISO 8601)
vendorSortBy OPTIONAL	string	Field to sort by
vendorSortOrder OPTIONAL	string	Sort direction (asc, desc)
page OPTIONAL	number	Page number (default: 1)
limit OPTIONAL	number	Results per page (default: 20, max: 100)

Response

Success (200 OK)

{
  "success": true,
  "data": [
    {
      "vendorId": "vnd_a1b2c3d4e5f6g7h8",
      "name": "Acme Referrals",
      "email": "partners@acmereferrals.com",
      "phone": "+14155551234",
      "status": "active",
      "commissionRate": 12.5,
      "commissionType": "percentage",
      "riskLevel": "low",
      "payoutFrequency": "monthly",
      "totalReferrals": 45,
      "activeReferrals": 38,
      "totalCommissionEarned": 15230.50,
      "kycStatus": "verified",
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-03-20T14:15:00.000Z"
    },
    {
      "vendorId": "vnd_b2c3d4e5f6g7h8i9",
      "name": "Global Partners Inc",
      "email": "ops@globalpartners.io",
      "phone": "+442071234567",
      "status": "active",
      "commissionRate": 10.0,
      "commissionType": "tiered",
      "riskLevel": "medium",
      "payoutFrequency": "weekly",
      "totalReferrals": 120,
      "activeReferrals": 95,
      "totalCommissionEarned": 48750.00,
      "kycStatus": "verified",
      "createdAt": "2023-11-01T08:00:00.000Z",
      "updatedAt": "2024-03-18T09:45:00.000Z"
    }
  ],
  "message": "Vendors retrieved successfully",
  "error": null,
  "meta": {
    "request_id": "req_xxxxx",
    "timestamp": "2024-03-21T10:30:00.000Z",
    "processing_time_ms": 85,
    "api_version": "v1",
    "endpoint": "GET /vendors",
    "user_type": "merchant",
    "pagination": {
      "page": 1,
      "limit": 20,
      "totalItems": 2,
      "totalPages": 1
    }
  }
}

Error Responses

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

Examples

cURL

curl -X GET "https://api.zenpayz.com/merchant/api/v1/vendors?status=active&riskLevel=low&page=1&limit=20" \
  -H "Authorization: Bearer zp_test_xxxxx" \
  -H "X-Timestamp: 2024-03-21T10:30:00.000Z" \
  -H "X-Signature: a1b2c3d4e5f6..." \
  -H "X-Secret-Salt: your_secret_salt" \
  -H "Content-Type: application/json"

JavaScript

const params = new URLSearchParams({
  status: 'active',
  riskLevel: 'low',
  page: '1',
  limit: '20',
});

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

const result = await response.json();
console.log(result.data); // Array of vendors
console.log(result.meta.pagination.totalItems); // Total count

SDK

const vendors = await zenpays.vendors.list({
  status: 'active',
  riskLevel: 'low',
  page: 1,
  limit: 20,
});

console.log(vendors.data); // Array of vendors
console.log(vendors.meta.pagination.totalItems); // Total count

Related Endpoints

• Create Vendor
• Get Vendor
• Vendor Stats