> ## Documentation Index
> Fetch the complete documentation index at: https://docs.juicyway.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk Transfers Overview

> Execute multiple transfers efficiently in a single batch operation

## Overview

Bulk transfers allow you to process multiple payments efficiently by grouping them into a single batch operation. This feature is ideal for handling payroll, mass payouts, or any scenario requiring multiple transfers to be processed together.

> [!NOTE]
>
> Before initiating bulk transfers:
>
> 1. Ensure sufficient balance for all transfers
> 2. Verify all beneficiary details
> 3. Check transfer limits for your account tier

## Key Features

> **Batch Processing**
>
> * Process up to 1,000 transfers per batch
> * Single API call for multiple transfers
> * Automatic validation of all entries
> * Bulk status tracking

> **Error Handling**
>
> * Individual transfer validation
> * Partial batch processing
> * Failed transfer retries
> * Detailed error reporting

> **Status Tracking**
>
> * Real-time batch status updates
> * Individual transfer tracking
> * Webhook notifications
> * Comprehensive reporting

> **Security Features**
>
> * Transfer PIN protection
> * Multi-factor authentication
> * Fraud detection
> * Rate limiting

## Supported Transfer Types

> **Bank Transfers**
>
> **Features**
>
> * NGN local transfers
> * USD international wires
> * CAD EFT payments
> * Multiple bank support
>
> **Limits**
>
> * Minimum: Currency equivalent of \$1
> * Maximum: Based on account tier
> * Daily limit: Based on account tier

> **Crypto Transfers**
>
> **Supported Tokens**
>
> * USDT (TRX, ETH networks)
> * USDC (ETH, MATIC networks)
>
> **Features**
>
> * Multi-chain support
> * Gas fee optimization
> * Rate conversion
> * Automated confirmations

> **Interac e-Transfers**
>
> **Features**
>
> * Canadian bank support
> * Email/phone transfers
> * Auto-deposit capability
> * Real-time notifications
>
> **Requirements**
>
> * Canadian bank account
> * Valid email/phone
> * Account verification

## Batch Lifecycle

**1. Creation**

Initialize batch with basic details:

* Batch reference
* Description
* Expiration time

**2. Adding Transfers**

Add transfers to the batch:

* Beneficiary details
* Transfer amounts
* Payment references
* Optional metadata

**3. Validation**

System validates:

* Beneficiary information
* Transfer limits
* Available balance
* Currency support

**4. Execution**

Process the batch:

* PIN authorization
* Transfer initiation
* Status tracking
* Webhook notifications

**5. Completion**

Final status updates:

* Success counts
* Failed transfers
* Retry options
* Detailed reporting

## Status Definitions

| Status | Description |
| - | - |
| created | Batch initialized but not executed |
| executing | Transfers being processed |
| completed | All transfers processed |
| cancelled | Batch cancelled before execution |
| expired | Batch expired without execution |

## Transaction Limits

> **Batch Limits**
>
> * Maximum transfers per batch: 1,000
> * Minimum transfers per batch: 2
> * Batch expiration: 24 hours from creation
> * Maximum retries per transfer: 3
>
> **Amount Limits**
>
> * Based on transfer type and currency
> * Subject to account tier limits
> * Daily and monthly caps apply

## Processing Times

> [!NOTE]
>
> Processing times vary by transfer type:
>
> * NGN transfers: 5-15 minutes
> * USD/International: 1-3 business days
> * Crypto transfers: Network-dependent
> * Interac e-Transfer: 15-30 minutes

## Best Practices

1. **Batch Organization**
   * Group similar transfers together
   * Use consistent currencies when possible
   * Include clear references
   * Set appropriate expiration times

2. **Error Handling**
   * Implement webhook monitoring
   * Handle partial successes
   * Retry failed transfers
   * Log all status changes

3. **Security**
   * Validate all beneficiary details
   * Use unique references
   * Monitor for suspicious patterns
   * Implement proper access controls

4. **Performance**
   * Optimize batch sizes
   * Schedule large batches appropriately
   * Monitor processing times
   * Track success rates

## Example Implementation

```javascript theme={null}
    Create Batch
// 1. Initialize batch
const batch = await juice.bulkTransfers.create({
  description: "March 2024 Payroll",
  expires_at: "2024-03-23T00:00:00Z",
  reference: "payroll-march-2024"
});

// 2. Add transfers
await juice.bulkTransfers.addTransfers({
  batch_id: batch.id,
  items: [
    {
      amount: 100000,
      beneficiary: {
      id: "juice-payout-5d906f6d-933b-4de9-927f-c7522823f5ec",
      type: "bank_account",
      },
      description: "March Salary - John",
      reference: "salary-john-march"
    },
    // Add more transfers...
  ]
});

// 3. Execute batch
await juice.bulkTransfers.execute(batch.id);

```

```javascript Monitor Status theme={null}
// Handle webhook events
app.post('/webhooks', (req, res) => {
  const event = req.body;
  
  switch(event.type) {
    case 'bulk_transfer.completed':
      // Handle completion
      break;
    case 'bulk_transfer.failed':
      // Handle failures
      break;
  }
  
  res.sendStatus(200);
});
```

> **Next Steps**
>
> Learn how to:
>
> * [Initialize Bulk Transfers](https://docs.juicyway.com/transfers/bulk-transfers/initiate-bulk-transfers.md)
> * [Add Transfers to Batch](https://docs.juicyway.com/transfers/bulk-transfers/update-bulk-transfer.md)
> * [Execute Bulk Transfers](https://docs.juicyway.com/transfers/bulk-transfers/execute-bulk-transfer.md)
> * [Monitor Transfer Status](https://docs.juicyway.com/transfers/bulk-transfers/get-bulk-transfer-details.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.