Batch Payouts

Batch payouts let you create multiple payouts in a single request, ideal for payroll, affiliate payments, or any scenario requiring many transfers at once. This guide covers best practices and implementation details.

Examples in this guide target the Sandbox (https://api.sandbox.zuba.com). Swap in https://api.zuba.com for production.

Why Use Batch Payouts

Efficiency: Create hundreds of payouts with a single API call, reducing API overhead
Per-payout results: Each item in the batch is processed independently. Failures are returned inline as { error, clientRef } objects in the 201 response array, alongside the successful payout objects
Up-front validation: Request-level validation is all-or-nothing. One malformed item rejects the entire batch with a 400 before anything is created

Single API Call for Multiple Payouts

The Zuba API accepts both single payout objects and arrays of payout objects at the same endpoint. Currency Fields: inputCurrency is the currency from your account you’ll be paying from, while currency is what the beneficiary will receive (automatic conversion if different):

// Batch payout data: EUR balance paying NGN salaries over local bank rails
const batchPayouts = [
  {
    clientRef: "SALARY-JAN-2026-001",
    amount: "850000.00",
    inputCurrency: "EUR",
    currency: "NGN",
    route: "bank_transfer",
    beneficiary: { id: "cc82fa1d-fc7a-478c-a734-d3bce40464e7" },
    reference: "January 2026 salary - John Doe",
    description: "Monthly salary payment"
  },
  {
    clientRef: "SALARY-JAN-2026-002",
    amount: "1200000.00",
    inputCurrency: "EUR",
    currency: "NGN",
    route: "bank_transfer",
    beneficiary: { id: "3f8e2a61-9b47-4c05-8d2e-1a6f0b9c4d73" },
    reference: "January 2026 salary - Jane Smith",
    description: "Monthly salary payment"
  },
  {
    clientRef: "SALARY-JAN-2026-003",
    amount: "650000.00",
    inputCurrency: "EUR",
    currency: "NGN",
    route: "bank_transfer",
    beneficiary: { id: "7d94c2e8-5f13-4a6b-9e07-2c8b1d4f6a90" },
    reference: "January 2026 salary - Bob Wilson",
    description: "Monthly salary payment"
  }
];

const response = await fetch('https://api.sandbox.zuba.com/v1/payouts', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
  },
  body: JSON.stringify(batchPayouts)
});

const results = await response.json();
console.log(`Submitted ${results.length} payouts`);

senderInfo is only needed when paying out on behalf of a third party. When omitted, your workspace is used as the business originator. Business originators use type: "business" with companyName, registrationNumber, and country.

For the live routes and destination currencies each rail supports, see Payment Routes or call GET /v1/payouts/available-rails.

Preparing Beneficiaries

Before creating batch payouts, ensure all beneficiaries exist. Here’s how to bulk create them:

async function createBeneficiaries(employeeData) {
  const beneficiaries = [];

  for (const employee of employeeData) {
    const beneficiaryData = {
      name: employee.name,
      email: employee.email,
      country: employee.country,
      accounts: [{
        type: "bank_account",
        currency: "NGN",
        data: {
          bankCode: employee.bankCode,   // 3-digit CBN code (e.g. "044") or 6-digit NIP code
          crAccount: employee.crAccount  // 10-digit account number
        }
      }]
    };

    try {
      const response = await fetch('https://api.sandbox.zuba.com/v1/beneficiaries', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
        },
        body: JSON.stringify(beneficiaryData)
      });

      const beneficiary = await response.json();
      beneficiaries.push({
        ...employee,
        beneficiaryId: beneficiary.id
      });
    } catch (error) {
      console.error(`Failed to create beneficiary for ${employee.name}:`, error);
    }
  }

  return beneficiaries;
}

Account data fields differ per destination. For example, iban accounts (EUR/GBP) require iban and accountHolderName, with bic optional. Use GET /v1/payouts/requirements to check the required fields for a currency, and see Account Types for every shape.

CSV Import Example

Process payroll data from a CSV file:

import csv from 'csv-parser';
import fs from 'fs';

async function processBatchPayoutsFromCSV(filePath) {
  const rows = [];

  return new Promise((resolve, reject) => {
    fs.createReadStream(filePath)
      .pipe(csv())
      .on('data', (row) => {
        // Validate row data
        if (!row.name || !row.amount || !row.crAccount) {
          console.warn('Skipping invalid row:', row);
          return;
        }

        rows.push({
          name: row.name,
          email: row.email,
          country: row.country,
          bankCode: row.bankCode,
          crAccount: row.crAccount,
          amount: row.amount, // keep as a decimal string, e.g. "850000.00"
          currency: row.currency || 'NGN',
          reference: row.reference,
          description: row.description
        });
      })
      .on('end', async () => {
        try {
          // Create beneficiaries first
          const beneficiaries = await createBeneficiaries(rows);

          // Create batch payouts
          const payoutRequests = beneficiaries.map((emp, index) => ({
            clientRef: `BATCH-${Date.now()}-${index}`,
            amount: emp.amount,
            inputCurrency: "EUR",
            currency: emp.currency,
            route: "bank_transfer",
            beneficiary: { id: emp.beneficiaryId },
            reference: emp.reference,
            description: emp.description
          }));

          const response = await fetch('https://api.sandbox.zuba.com/v1/payouts', {
            method: 'POST',
            headers: {
              'Content-Type': 'application/json',
              'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
            },
            body: JSON.stringify(payoutRequests)
          });

          const results = await response.json();
          resolve(results);
        } catch (error) {
          reject(error);
        }
      })
      .on('error', reject);
  });
}

Monitoring Batch Progress

Webhooks are the primary mechanism for tracking payout status: subscribe once and receive an event every time a payout in the batch transitions (for example to processing, paid, or failed), with no polling. If you do need to poll, prefer GET /v1/payouts (the list endpoint) over per-ID requests. For a small batch, per-ID polling looks like this:

async function monitorBatchPayouts(payoutIds) {
  const statusUpdates = [];

  for (const payoutId of payoutIds) {
    try {
      const response = await fetch(`https://api.sandbox.zuba.com/v1/payouts/${payoutId}`, {
        headers: {
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
        }
      });

      const payout = await response.json();
      statusUpdates.push({
        id: payout.id,
        reference: payout.reference,
        status: payout.status,
        amount: payout.amount,
        beneficiaryName: payout.beneficiary.name
      });
    } catch (error) {
      console.error(`Error checking payout ${payoutId}:`, error);
    }
  }

  return statusUpdates;
}

Error Handling in Batches

Batch creation is not atomic. There are two distinct failure modes:

Validation failure (400): if any payout in the array fails request validation, the entire batch is rejected before anything is created. details contains per-field errors ({ field, message }) for the first invalid payout.
Per-payout failure (inside a 201): once validation passes, each payout is processed independently. A payout that cannot be created (for example, insufficient balance or a duplicate clientRef) is returned as an inline { error, clientRef } element in the response array; the other payouts succeed normally.

Handle both:

async function createBatchWithErrorHandling(payoutRequests) {
  const response = await fetch('https://api.sandbox.zuba.com/v1/payouts', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
    },
    body: JSON.stringify(payoutRequests)
  });

  if (!response.ok) {
    // Validation failed: nothing in the batch was created.
    const error = await response.json();
    if (Array.isArray(error.details)) {
      error.details.forEach(({ field, message }) => {
        console.error(`Validation error on ${field}: ${message}`);
      });
    }
    throw new Error(error.message);
  }

  // 201: the array mixes created payouts and inline failures
  const results = await response.json();
  const created = results.filter((r) => 'id' in r);
  const failed = results.filter((r) => 'error' in r);

  created.forEach((payout) => {
    console.log(`Created ${payout.clientRef}: ${payout.id} - ${payout.status}`);
  });
  failed.forEach(({ clientRef, error }) => {
    console.error(`Failed ${clientRef}: ${error}`);
  });

  // Alert on failed rows: they were NOT created and need follow-up
  return { created, failed };
}

Retries and Idempotency

clientRef is unique per workspace, which makes retries safe by construction:

A single-payout request that reuses a clientRef is rejected with 400 Payout with this client reference already exists.
In a batch, a duplicate clientRef surfaces as an inline { error, clientRef } element in the 201 response array; the other rows are unaffected.
Re-submitting a partially failed batch is therefore safe: rows that were already created come back as duplicate errors, and only the previously failed rows create payouts.

The endpoint also supports an optional Idempotency-Key header for transport-level retries: a repeat with the same key and the same body replays the original response without creating new payouts; the same key with a different body is rejected with 422; a repeat while the original request is still in flight returns a retryable 409. Keys expire 24 hours after the original request completes.

Best Practices

1. Batch Size Limits

Keep batch sizes reasonable to avoid timeouts:

const BATCH_SIZE = 100;

async function processBatchesInChunks(payouts) {
  const created = [];
  const failed = [];

  for (let i = 0; i < payouts.length; i += BATCH_SIZE) {
    const batch = payouts.slice(i, i + BATCH_SIZE);

    try {
      const results = await createBatchWithErrorHandling(batch);
      created.push(...results.created);
      failed.push(...results.failed);

      // Pace requests under the rate limits; on a 429, back off and retry
      // instead of a fixed sleep (see Retries and Idempotency above).
      await new Promise(resolve => setTimeout(resolve, 1000));
    } catch (error) {
      console.error(`Batch ${i / BATCH_SIZE + 1} rejected:`, error);
    }
  }

  return { created, failed };
}

2. Validation Before Submission

Validate all payout data before submission. The lists below cover the live destination currencies and routes; prefer GET /v1/payouts/available-rails and GET /v1/payouts/requirements to check availability dynamically:

const SUPPORTED_CURRENCIES = ['EUR', 'USD', 'GBP', 'USDC', 'USDT', 'EURC', 'NGN', 'XOF', 'XAF', 'GHS', 'KES', 'UGX'];
const SUPPORTED_ROUTES = ['bank_transfer', 'ach', 'fedwire', 'swift', 'crypto', 'mobile_money'];

function validateBatchPayouts(payouts) {
  const errors = [];

  payouts.forEach((payout, index) => {
    if (!payout.clientRef) {
      errors.push(`Payout ${index + 1}: Missing clientRef`);
    }

    if (!payout.beneficiary?.id) {
      errors.push(`Payout ${index + 1}: Missing beneficiary.id`);
    }

    const amount = parseFloat(payout.amount);
    if (!payout.amount || isNaN(amount) || amount <= 0) {
      errors.push(`Payout ${index + 1}: Invalid amount`);
    }

    if (!SUPPORTED_CURRENCIES.includes(payout.currency)) {
      errors.push(`Payout ${index + 1}: Unsupported currency`);
    }

    if (!SUPPORTED_ROUTES.includes(payout.route)) {
      errors.push(`Payout ${index + 1}: Invalid route`);
    }
  });

  return errors;
}

// Usage
const validationErrors = validateBatchPayouts(batchPayouts);
if (validationErrors.length > 0) {
  console.error('Validation errors:', validationErrors);
  return;
}

3. Progress Reporting

Implement progress tracking for large batches:

async function createBatchWithProgress(payouts, onProgress) {
  const created = [];
  const failed = [];
  const total = payouts.length;

  for (let i = 0; i < total; i += BATCH_SIZE) {
    const batch = payouts.slice(i, i + BATCH_SIZE);
    const results = await createBatchWithErrorHandling(batch);

    created.push(...results.created);
    failed.push(...results.failed);

    // Report progress
    const processed = Math.min(i + BATCH_SIZE, total);
    onProgress(processed, total, (processed / total) * 100);
  }

  return { created, failed };
}

// Usage
const { created, failed } = await createBatchWithProgress(batchData, (current, total, percent) => {
  console.log(`Progress: ${current}/${total} (${percent.toFixed(1)}%)`);
});

Complete Batch Payout Example

Here’s a complete implementation:

import Decimal from 'decimal.js';

class BatchPayoutProcessor {
  constructor(apiToken, baseURL = 'https://api.sandbox.zuba.com/v1') {
    this.apiToken = apiToken;
    this.baseURL = baseURL;
    this.headers = {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiToken}`
    };
  }

  async processPayroll(employeeData) {
    try {
      // 1. Create beneficiaries
      const beneficiaries = await this.createBeneficiaries(employeeData);

      // 2. Prepare payout requests. clientRef is unique per workspace, so a
      // re-run of the same payroll period cannot double-pay anyone.
      const payoutRequests = beneficiaries.map((emp) => ({
        clientRef: `PAYROLL-2026-01-${emp.employeeId}`,
        amount: emp.salary, // decimal string, e.g. "850000.00"
        inputCurrency: 'EUR',
        currency: 'NGN',
        route: 'bank_transfer',
        beneficiary: { id: emp.beneficiaryId },
        reference: `Monthly salary - ${emp.name}`,
        description: `Payroll payment for ${emp.name}`
      }));

      // 3. Validate payouts
      const errors = this.validatePayouts(payoutRequests);
      if (errors.length > 0) {
        throw new Error(`Validation failed: ${errors.join(', ')}`);
      }

      // 4. Create batch payouts
      const results = await this.createBatch(payoutRequests);

      // 5. Return summary. amount is a decimal string on the wire: sum with
      // a decimal library, never float arithmetic; error rows carry no amount
      // and are excluded.
      const created = results.filter((r) => 'id' in r);
      const failed = results.filter((r) => 'error' in r);

      return {
        total: results.length,
        successful: created.length,
        failed,
        totalAmount: created
          .reduce((sum, p) => sum.plus(p.amount), new Decimal(0))
          .toFixed(2),
        payouts: created
      };

    } catch (error) {
      console.error('Payroll processing failed:', error);
      throw error;
    }
  }

  async createBatch(payouts) {
    const response = await fetch(`${this.baseURL}/payouts`, {
      method: 'POST',
      headers: this.headers,
      body: JSON.stringify(payouts)
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.message);
    }

    return await response.json();
  }

  // ... other methods
}

// Usage
const processor = new BatchPayoutProcessor(process.env.ZUBA_API_TOKEN);
const results = await processor.processPayroll(employeeData);
console.log(`Processed ${results.successful}/${results.total} payouts`);

Next Steps

Set up webhooks to receive real-time status updates for your batch payouts
Learn about error handling strategies for production batch processing
Explore the API reference for advanced payout options

Get Started

Core Concepts

Guides

Batch Payouts

Why Use Batch Payouts

Single API Call for Multiple Payouts

Preparing Beneficiaries

CSV Import Example

Monitoring Batch Progress

Error Handling in Batches

Retries and Idempotency

Best Practices

1. Batch Size Limits

2. Validation Before Submission

3. Progress Reporting

Complete Batch Payout Example

Next Steps

​Why Use Batch Payouts

​Single API Call for Multiple Payouts

​Preparing Beneficiaries

​CSV Import Example

​Monitoring Batch Progress

​Error Handling in Batches

​Retries and Idempotency

​Best Practices

​1. Batch Size Limits

​2. Validation Before Submission

​3. Progress Reporting

​Complete Batch Payout Example

​Next Steps

Why Use Batch Payouts

Single API Call for Multiple Payouts

Preparing Beneficiaries

CSV Import Example

Monitoring Batch Progress

Error Handling in Batches

Retries and Idempotency

Best Practices

1. Batch Size Limits

2. Validation Before Submission

3. Progress Reporting

Complete Batch Payout Example

Next Steps