Create Batch Payout

Create a batch payout from a JSON array of payout items. All items must use the same currency. Returns a validated batch that must be confirmed before processing begins.

POSThttps://api.zenpays.com/payment/api/v1/batch-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
X-Idempotency-Key OPTIONAL	Unique key to prevent duplicate batches

Body Parameters

Parameter	Type	Description
items REQUIRED	array	Array of payout items (max 1000)
currency REQUIRED	string	3-character currency code (all items must match)
webhookUrl OPTIONAL	string	URL for batch status webhooks
metadata OPTIONAL	object	Custom key-value pairs

Item Fields

Parameter	Type	Description
beneficiaryName REQUIRED	string	Beneficiary name
beneficiaryAccount OPTIONAL	string	Account number (required for bank transfers)
beneficiaryIfsc OPTIONAL	string	IFSC code (India bank transfers)
beneficiaryVpa OPTIONAL	string	UPI VPA (required for UPI payouts)
beneficiarySwift OPTIONAL	string	SWIFT code (international transfers)
beneficiaryIban OPTIONAL	string	IBAN (international transfers)
beneficiaryBankCode OPTIONAL	string	Bank code
bankName OPTIONAL	string	Bank name
beneficiaryEmail OPTIONAL	string	Beneficiary email
beneficiaryMobile OPTIONAL	string	Beneficiary mobile
amount REQUIRED	number	Payout amount (must be > 0)
currency REQUIRED	string	Must match the batch currency
payoutType REQUIRED	string	bank_transfer, imps, neft, rtgs, upi, or crypto
purpose OPTIONAL	string	Purpose (e.g., SALARY, REFUND, PAYOUT)
customerId OPTIONAL	string	Associated customer ID
description OPTIONAL	string	Description

Response

Success (200 OK)

{
  "success": true,
  "data": {
    "batchId": "batch_xxxxx",
    "totalPayouts": 3,
    "totalAmount": 15000,
    "currency": "INR",
    "estimatedFees": 90,
    "totalDebitedAmount": 15090,
    "status": "validated",
    "message": "Batch payout created and validated successfully. Call confirm to start processing.",
    "previewData": [
      {
        "rowNumber": 1,
        "beneficiaryName": "Alice Smith",
        "amount": 5000,
        "currency": "INR",
        "payoutType": "imps",
        "beneficiaryAccount": "1234567890"
      }
    ]
  }
}

Validation Error Response

{
  "success": false,
  "data": {
    "validationErrors": [
      { "row": 2, "field": "beneficiaryAccount", "message": "Account number is required for bank transfer payouts" },
      { "row": 3, "field": "currency", "message": "Currency must be INR. Mixed currencies are not allowed in a single batch." }
    ],
    "message": "Validation failed: 2 error(s) found"
  }
}

Error Responses

Code	HTTP	Message
BATCH_PAYOUT_CREATE_FAILED	400	Validation failed or empty items
UNAUTHORIZED	401	Invalid API key

Examples

cURL

curl -X POST https://api.zenpays.com/payment/api/v1/batch-payouts \
  -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 '{
    "items": [
      {
        "beneficiaryName": "Alice Smith",
        "beneficiaryAccount": "1234567890",
        "beneficiaryIfsc": "HDFC0001234",
        "amount": 5000,
        "currency": "INR",
        "payoutType": "imps",
        "purpose": "SALARY"
      },
      {
        "beneficiaryName": "Bob Johnson",
        "beneficiaryVpa": "bob@upi",
        "amount": 3000,
        "currency": "INR",
        "payoutType": "upi",
        "purpose": "COMMISSION"
      }
    ],
    "currency": "INR"
  }'

SDK

const batch = await zenpays.payouts.createBatch({
  items: [
    {
      beneficiaryName: 'Alice Smith',
      beneficiaryAccount: '1234567890',
      beneficiaryIfsc: 'HDFC0001234',
      amount: 5000,
      currency: 'INR',
      payoutType: 'imps',
      purpose: 'SALARY',
    },
    {
      beneficiaryName: 'Bob Johnson',
      beneficiaryVpa: 'bob@upi',
      amount: 3000,
      currency: 'INR',
      payoutType: 'upi',
      purpose: 'COMMISSION',
    },
  ],
  currency: 'INR',
})

console.log(batch.batchId)  // 'batch_xxxxx'
console.log(batch.status)   // 'validated'

Batch Lifecycle

1. Create — POST /batch-payouts → status: validated
2. Confirm — POST /batch-payouts/{id}/confirm → status: processing
3. Poll — GET /batch-payouts/{id} → status: completed | partially_completed | failed
4. Inspect — GET /batch-payouts/{id}/payouts → individual payout statuses

Related Endpoints

• Confirm Batch Payout
• Get Batch Payout
• List Batch Payouts
• Cancel Batch Payout