Upload Batch Payout

Upload multiple payouts in a single API call using a CSV or Excel file. Use Batch Payout Template to get the correct column headers and field definitions before building your file.

POSThttps://api.zenpays.com/payment/api/v1/batch-payouts/upload

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
X-Merchant-Id REQUIRED	Your merchant ID
X-Request-Id OPTIONAL	Idempotency key for the request
Content-Type REQUIRED	multipart/form-data

Body Parameters

Parameter	Type	Description
file REQUIRED	File	CSV or Excel file (max 5MB). Accepted: .csv, .xlsx, .xls
webhookUrl OPTIONAL	string	URL for batch status webhooks

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "batch_id": "batch_1774867295648_06f4074d",
    "total_payouts": 5,
    "total_amount": 50000,
    "currency": "INR",
    "estimated_fees": 125,
    "status": "validated",
    "message": "Batch payout uploaded and validated successfully",
    "preview_data": [
      {
        "row_number": 1,
        "customer_email": "[email protected]",
        "beneficiary_name": "Rajesh Kumar",
        "amount": 10000,
        "currency": "INR",
        "payout_type": "IMPS",
        "beneficiary_account": "1234567890"
      }
    ],
    "validation_errors": []
  }
}

Response Fields

Parameter	Type	Description
batch_id OPTIONAL	string	Unique identifier for the batch
total_payouts OPTIONAL	number	Number of payout rows parsed
total_amount OPTIONAL	number	Sum of all payout amounts
currency OPTIONAL	string	Currency code from the file
estimated_fees OPTIONAL	number	Estimated processing fees
status OPTIONAL	string	Batch status after upload (validated)
message OPTIONAL	string	Human-readable status message
preview_data OPTIONAL	array	Preview of the first rows in the batch
validation_errors OPTIONAL	array	Per-row validation errors (empty when all rows pass)

note

After upload, the batch is in validated status. You must call Confirm Batch Payout to start processing.

Error Responses

Code	HTTP	Message
MISSING_FILE	400	No file uploaded
BATCH_UPLOAD_FAILED	400	File parsing or validation failed
UNAUTHORIZED	401	Invalid API key

Examples

cURL

curl -X POST "https://api.zenpays.com/payment/api/v1/batch-payouts/upload" \
  -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 "X-Merchant-Id: ZP_FIN_xxxxx" \
  -H "X-Request-Id: req_unique_id" \
  -F "[email protected]" \
  -F "webhookUrl=https://your-server.com/webhooks/batch-payout"

SDK (Recommended)

const result = await zenpays.payouts.uploadBatch({
  filePath: './batch-payouts.csv',
  webhookUrl: 'https://your-server.com/webhooks/batch-payout',
});

console.log(`Batch ID: ${result.batch_id}`);
console.log(`Total payouts: ${result.total_payouts}`);
console.log(`Total amount: ${result.total_amount} ${result.currency}`);
console.log(`Estimated fees: ${result.estimated_fees}`);

if (result.validation_errors.length > 0) {
  console.error('Validation errors:', result.validation_errors);
} else {
  // Confirm the batch to start processing
  await zenpays.payouts.confirmBatch(result.batch_id);
}

JavaScript

const timestamp = new Date().toISOString();
const signature = crypto
  .createHmac('sha256', secretSalt)
  .update(timestamp)
  .digest('hex');

const formData = new FormData();
formData.append('file', fs.createReadStream('./batch-payouts.csv'));
formData.append('webhookUrl', 'https://your-server.com/webhooks/batch-payout');

const response = await fetch(
  'https://api.zenpays.com/payment/api/v1/batch-payouts/upload',
  {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'X-Timestamp': timestamp,
      'X-Signature': signature,
      'X-Secret-Salt': secretSalt,
      'X-Merchant-Id': merchantId,
      'X-Request-Id': `req_${Date.now()}`,
    },
    body: formData,
  }
);

const { data } = await response.json();
console.log(`Batch ${data.batch_id}: ${data.total_payouts} payouts, ${data.status}`);

Related Endpoints

• Batch Payout Template — Get column definitions and sample CSV
• Create Batch Payout — Create a batch payout via JSON
• Confirm Batch Payout — Confirm and start processing a batch
• Get Batch Payout — Check batch status