Create Vendor

Create a new vendor record for managing referral partnerships and commission payouts.

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

Body Parameters

Parameter	Type	Description
name REQUIRED	string	Vendor display name
description OPTIONAL	string	Vendor description
email REQUIRED	string	Vendor email address (must be valid email)
phone OPTIONAL	string	Vendor phone number
website OPTIONAL	string	Vendor website URL
status OPTIONAL	string	Initial status (active, inactive, suspended, pending)
contactInfo REQUIRED	object	Contact information object
businessInfo REQUIRED	object	Business information
commissionRate REQUIRED	number	Commission rate (0-100)
commissionType REQUIRED	string	Commission model (percentage, fixed, tiered)
commissionConfig OPTIONAL	object	Additional commission configuration (e.g., tier brackets)
riskLevel OPTIONAL	string	Risk classification (low, medium, high, critical)
payoutFrequency REQUIRED	string	Payout schedule (weekly, monthly, quarterly)
bankDetails REQUIRED	object	Bank account for payouts
environment OPTIONAL	string	Environment identifier
metadata OPTIONAL	object	Custom key-value pairs

Response

Success (201 Created)

{
  "success": true,
  "data": {
    "vendorId": "vnd_a1b2c3d4e5f6g7h8",
    "name": "Acme Referrals",
    "description": "Strategic referral partner for APAC region",
    "email": "partners@acmereferrals.com",
    "phone": "+14155551234",
    "website": "https://acmereferrals.com",
    "status": "active",
    "contactInfo": {
      "primaryContact": {
        "firstName": "Sarah",
        "lastName": "Chen",
        "email": "sarah.chen@acmereferrals.com",
        "phone": "+14155551235",
        "designation": "Partnerships Director"
      },
      "address": {
        "street": "100 Market Street",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94105",
        "country": "US"
      }
    },
    "businessInfo": {
      "registrationNumber": "REG-2024-78901",
      "taxId": "87-6543210",
      "businessType": "LLC",
      "incorporationDate": "2020-03-15",
      "monthlyVolume": 500000
    },
    "commissionRate": 12.5,
    "commissionType": "percentage",
    "commissionConfig": null,
    "riskLevel": "low",
    "payoutFrequency": "monthly",
    "bankDetails": {
      "accountNumber": "****6789",
      "routingNumber": "****4321",
      "bankName": "First National Bank",
      "swiftCode": "FNBKUS33",
      "beneficiaryName": "Acme Referrals LLC",
      "accountType": "current",
      "payoutType": "wire"
    },
    "environment": "production",
    "metadata": {},
    "createdAt": "2024-01-15T10:30:00.000Z",
    "updatedAt": "2024-01-15T10:30:00.000Z"
  },
  "message": "Vendor created successfully",
  "error": null,
  "meta": {
    "request_id": "req_xxxxx",
    "timestamp": "2024-01-15T10:30:00.000Z",
    "processing_time_ms": 145,
    "api_version": "v1",
    "endpoint": "POST /vendors",
    "user_type": "merchant"
  }
}

Error Responses

Code	HTTP	Message
VALIDATION_ERROR	400	Invalid request parameters
UNAUTHORIZED	401	Invalid API key
DUPLICATE_VENDOR	409	Vendor with this email already exists

Examples

cURL

curl -X POST https://api.zenpayz.com/merchant/api/v1/vendors \
  -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" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Referrals",
    "description": "Strategic referral partner for APAC region",
    "email": "partners@acmereferrals.com",
    "phone": "+14155551234",
    "website": "https://acmereferrals.com",
    "contactInfo": {
      "primaryContact": {
        "firstName": "Sarah",
        "lastName": "Chen",
        "email": "sarah.chen@acmereferrals.com",
        "phone": "+14155551235",
        "designation": "Partnerships Director"
      },
      "address": {
        "street": "100 Market Street",
        "city": "San Francisco",
        "state": "CA",
        "postalCode": "94105",
        "country": "US"
      }
    },
    "businessInfo": {
      "registrationNumber": "REG-2024-78901",
      "taxId": "87-6543210",
      "businessType": "LLC",
      "incorporationDate": "2020-03-15",
      "monthlyVolume": 500000
    },
    "commissionRate": 12.5,
    "commissionType": "percentage",
    "riskLevel": "low",
    "payoutFrequency": "monthly",
    "bankDetails": {
      "accountNumber": "9876543210",
      "routingNumber": "021000021",
      "bankName": "First National Bank",
      "swiftCode": "FNBKUS33",
      "beneficiaryName": "Acme Referrals LLC",
      "accountType": "current",
      "payoutType": "wire"
    }
  }'

JavaScript

const response = await fetch('https://api.zenpayz.com/merchant/api/v1/vendors', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
    'X-Secret-Salt': secretSalt,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Acme Referrals',
    description: 'Strategic referral partner for APAC region',
    email: 'partners@acmereferrals.com',
    phone: '+14155551234',
    website: 'https://acmereferrals.com',
    contactInfo: {
      primaryContact: {
        firstName: 'Sarah',
        lastName: 'Chen',
        email: 'sarah.chen@acmereferrals.com',
        phone: '+14155551235',
        designation: 'Partnerships Director',
      },
      address: {
        street: '100 Market Street',
        city: 'San Francisco',
        state: 'CA',
        postalCode: '94105',
        country: 'US',
      },
    },
    businessInfo: {
      registrationNumber: 'REG-2024-78901',
      taxId: '87-6543210',
      businessType: 'LLC',
      incorporationDate: '2020-03-15',
      monthlyVolume: 500000,
    },
    commissionRate: 12.5,
    commissionType: 'percentage',
    riskLevel: 'low',
    payoutFrequency: 'monthly',
    bankDetails: {
      accountNumber: '9876543210',
      routingNumber: '021000021',
      bankName: 'First National Bank',
      swiftCode: 'FNBKUS33',
      beneficiaryName: 'Acme Referrals LLC',
      accountType: 'current',
      payoutType: 'wire',
    },
  }),
});

const result = await response.json();
console.log(result.data.vendorId); // vnd_a1b2c3d4e5f6g7h8

SDK

const vendor = await zenpays.vendors.create({
  name: 'Acme Referrals',
  description: 'Strategic referral partner for APAC region',
  email: 'partners@acmereferrals.com',
  phone: '+14155551234',
  website: 'https://acmereferrals.com',
  contactInfo: {
    primaryContact: {
      firstName: 'Sarah',
      lastName: 'Chen',
      email: 'sarah.chen@acmereferrals.com',
      phone: '+14155551235',
      designation: 'Partnerships Director',
    },
    address: {
      street: '100 Market Street',
      city: 'San Francisco',
      state: 'CA',
      postalCode: '94105',
      country: 'US',
    },
  },
  businessInfo: {
    registrationNumber: 'REG-2024-78901',
    taxId: '87-6543210',
    businessType: 'LLC',
    incorporationDate: '2020-03-15',
    monthlyVolume: 500000,
  },
  commissionRate: 12.5,
  commissionType: 'percentage',
  riskLevel: 'low',
  payoutFrequency: 'monthly',
  bankDetails: {
    accountNumber: '9876543210',
    routingNumber: '021000021',
    bankName: 'First National Bank',
    swiftCode: 'FNBKUS33',
    beneficiaryName: 'Acme Referrals LLC',
    accountType: 'current',
    payoutType: 'wire',
  },
});

console.log(vendor.vendorId); // vnd_a1b2c3d4e5f6g7h8

Related Endpoints

• List Vendors
• Get Vendor
• Update Vendor
• Delete Vendor