Batch Payout Template

Get the CSV template for batch payouts. Returns column definitions, sample data, and field descriptions so you can build a spreadsheet or generate a CSV file for batch payout uploads.

When to use

Call this endpoint before uploading a batch payout to discover which fields are required and optional. Pass currency and country query parameters to get a template customized for the target region.

GEThttps://api.zenpays.com/payment/api/v1/batch-payouts/template

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

Query Parameters

Parameter	Type	Description
currency OPTIONAL	string	Currency code to customize template (e.g. INR, USD)
country OPTIONAL	string	ISO country code to customize template (e.g. IN, US)

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "columns": [
      "customer_email",
      "customer_phone",
      "amount",
      "currency",
      "beneficiary_name",
      "payout_type",
      "purpose",
      "beneficiary_account",
      "beneficiary_ifsc",
      "beneficiary_vpa",
      "beneficiary_swift",
      "beneficiary_iban",
      "bank_name",
      "description",
      "country_code",
      "document_id"
    ],
    "requiredColumns": [
      "customer_email",
      "customer_phone",
      "amount",
      "currency",
      "beneficiary_name",
      "payout_type",
      "purpose"
    ],
    "optionalColumns": [
      "beneficiary_account",
      "beneficiary_ifsc",
      "beneficiary_swift",
      "beneficiary_iban",
      "beneficiary_vpa",
      "bank_name",
      "description",
      "country_code",
      "document_id"
    ],
    "sampleRow": {
      "customer_email": "[email protected]",
      "customer_phone": "+919876543210",
      "amount": "1000",
      "currency": "INR",
      "beneficiary_name": "Rajesh Kumar",
      "payout_type": "IMPS",
      "purpose": "PAYOUT",
      "beneficiary_account": "1234567890",
      "beneficiary_ifsc": "HDFC0001234"
    },
    "csvTemplate": "customer_email,customer_phone,amount,currency,beneficiary_name,payout_type,purpose,beneficiary_account,beneficiary_ifsc,...\[email protected],+919876543210,1000,INR,Rajesh Kumar,IMPS,PAYOUT,1234567890,HDFC0001234,...",
    "fieldDescriptions": {
      "customer_email": "Customer email address (required)",
      "customer_phone": "Customer phone with country code (required)",
      "amount": "Payout amount, must be > 0 (required)",
      "currency": "Currency code e.g. INR, USD (required)",
      "beneficiary_name": "Full name of beneficiary (required)",
      "payout_type": "IMPS, NEFT, RTGS, UPI, or BANK_TRANSFER (required)",
      "purpose": "SALARY, REFUND, PAYOUT, COMMISSION, or CASHBACK (required)",
      "beneficiary_account": "Bank account number (required for bank transfers)",
      "beneficiary_ifsc": "IFSC code for Indian banks",
      "beneficiary_vpa": "UPI VPA (required for UPI payouts)",
      "beneficiary_swift": "SWIFT code for international",
      "beneficiary_iban": "IBAN for international",
      "bank_name": "Bank name",
      "description": "Optional description",
      "country_code": "2-letter ISO country code",
      "document_id": "Government document ID"
    }
  }
}

Field Descriptions

Parameter	Type	Description
columns OPTIONAL	string[]	All available column headers for the CSV
requiredColumns OPTIONAL	string[]	Columns that must be filled for every row
optionalColumns OPTIONAL	string[]	Columns that may be left empty
sampleRow OPTIONAL	object	Example row with realistic values
csvTemplate OPTIONAL	string	Ready-to-use CSV string with headers and sample row
fieldDescriptions OPTIONAL	object	Human-readable description for each column

tip

Download the csvTemplate string and save as a .csv file, or use the columns array to build your own spreadsheet. Fill in rows and upload via the Upload Batch Payout endpoint.

Error Responses

Code	HTTP	Message
UNAUTHORIZED	401	Invalid API key

Examples

cURL

curl -X GET "https://api.zenpays.com/payment/api/v1/batch-payouts/template?currency=INR&country=IN" \
  -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"

SDK (Recommended)

const template = await zenpays.payouts.getBatchTemplate({
  currency: 'INR',
  country: 'IN',
});

console.log('Required columns:', template.requiredColumns);
console.log('CSV template:', template.csvTemplate);

// Save csvTemplate to a file
fs.writeFileSync('batch-payout-template.csv', template.csvTemplate);

JavaScript

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

const response = await fetch(
  'https://api.zenpays.com/payment/api/v1/batch-payouts/template?currency=INR&country=IN',
  {
    method: 'GET',
    headers: {
      'Authorization': `Bearer ${apiKey}`,
      'X-Timestamp': timestamp,
      'X-Signature': signature,
      'X-Secret-Salt': secretSalt,
      'X-Merchant-Id': merchantId,
      'X-Request-Id': `req_${Date.now()}`,
    },
  }
);

const { data: template } = await response.json();
console.log('Required columns:', template.requiredColumns);
console.log('Field descriptions:', template.fieldDescriptions);

Related Endpoints

• Upload Batch Payout — Upload a CSV/Excel file with payout rows
• Create Batch Payout — Create a batch payout via JSON
• Confirm Batch Payout — Confirm and start processing a batch
• Get Batch Payout — Check batch status