Vendor Payout

Initiate a commission payout to a vendor. This triggers a transfer of earned commissions to the vendor's registered bank account.

POSThttps://api.zenpayz.com/merchant/api/v1/vendors/:id/payouts

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

Path Parameters

Parameter	Type	Description
id REQUIRED	string	Vendor ID (e.g., vnd_a1b2c3d4e5f6g7h8)

Body Parameters

Parameter	Type	Description
amount OPTIONAL	number	Payout amount (min: 0). If omitted, pays all pending commissions
currency REQUIRED	string	Currency code (e.g., USD, EUR, INR)
paymentMethod OPTIONAL	string	Payout method override
adminNotes OPTIONAL	string	Internal notes about this payout
environment REQUIRED	string	Environment identifier

Response

Success (201 Created)

{
  "success": true,
  "data": {
    "payoutId": "pyt_n4o5p6q7r8s9t0u1",
    "vendorId": "vnd_a1b2c3d4e5f6g7h8",
    "amount": 5312.50,
    "currency": "USD",
    "status": "processing",
    "paymentMethod": "wire",
    "commissionsIncluded": 12,
    "bankDetails": {
      "bankName": "First National Bank",
      "beneficiaryName": "Acme Referrals LLC",
      "accountNumber": "****6789"
    },
    "adminNotes": "Q1 2024 commission payout",
    "environment": "production",
    "initiatedAt": "2024-03-21T16:00:00.000Z",
    "estimatedArrival": "2024-03-24T16:00:00.000Z"
  },
  "message": "Vendor payout initiated successfully",
  "error": null,
  "meta": {
    "request_id": "req_xxxxx",
    "timestamp": "2024-03-21T16:00:00.000Z",
    "processing_time_ms": 250,
    "api_version": "v1",
    "endpoint": "POST /vendors/:id/payouts",
    "user_type": "merchant"
  }
}

Error Responses

Code	HTTP	Message
VALIDATION_ERROR	400	Invalid request parameters
INSUFFICIENT_BALANCE	400	Payout amount exceeds pending commissions
UNAUTHORIZED	401	Invalid API key
VENDOR_NOT_FOUND	404	Vendor with specified ID does not exist
PAYOUT_IN_PROGRESS	409	A payout is already being processed for this vendor
KYC_NOT_VERIFIED	422	Vendor KYC must be verified before payouts

Examples

cURL

curl -X POST https://api.zenpayz.com/merchant/api/v1/vendors/vnd_a1b2c3d4e5f6g7h8/payouts \
  -H "Authorization: Bearer zp_test_xxxxx" \
  -H "X-Timestamp: 2024-03-21T16:00:00.000Z" \
  -H "X-Signature: a1b2c3d4e5f6..." \
  -H "X-Secret-Salt: your_secret_salt" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5312.50,
    "currency": "USD",
    "paymentMethod": "wire",
    "adminNotes": "Q1 2024 commission payout",
    "environment": "production"
  }'

JavaScript

const response = await fetch('https://api.zenpayz.com/merchant/api/v1/vendors/vnd_a1b2c3d4e5f6g7h8/payouts', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'X-Timestamp': timestamp,
    'X-Signature': signature,
    'X-Secret-Salt': secretSalt,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    amount: 5312.50,
    currency: 'USD',
    paymentMethod: 'wire',
    adminNotes: 'Q1 2024 commission payout',
    environment: 'production',
  }),
});

const result = await response.json();
console.log(result.data.payoutId); // pyt_n4o5p6q7r8s9t0u1
console.log(result.data.status); // processing

SDK

const payout = await zenpays.vendors.createPayout('vnd_a1b2c3d4e5f6g7h8', {
  amount: 5312.50,
  currency: 'USD',
  paymentMethod: 'wire',
  adminNotes: 'Q1 2024 commission payout',
  environment: 'production',
});

console.log(payout.payoutId); // pyt_n4o5p6q7r8s9t0u1
console.log(payout.status); // processing

Related Endpoints

• Vendor Commissions
• Get Vendor
• Vendor Analytics