# 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](/docs/rest-api/endpoints/payouts/confirm-batch-payout) before processing begins. ## Request ### Headers ### Body Parameters ### Item Fields 0)" }, { name: "currency", type: "string", required: true, desc: "Must match the batch `currency`" }, { name: "payoutType", type: "string", required: true, desc: "`bank_transfer`, `imps`, `neft`, `rtgs`, `upi`, or `crypto`" }, { name: "purpose", type: "string", desc: "Purpose (e.g., `SALARY`, `REFUND`, `PAYOUT`)" }, { name: "customerId", type: "string", desc: "Associated customer ID" }, { name: "description", type: "string", desc: "Description" }, ]} /> ## Response ### Success (200 OK) ```json { "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 ```json { "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 ## Examples ```bash 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" }' ``` ```javascript 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](/docs/rest-api/endpoints/payouts/confirm-batch-payout) - [Get Batch Payout](/docs/rest-api/endpoints/payouts/get-batch-payout) - [List Batch Payouts](/docs/rest-api/endpoints/payouts/list-batch-payouts) - [Cancel Batch Payout](/docs/rest-api/endpoints/payouts/cancel-batch-payout)