> ## 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
</Note>

## Key Features

<CardGroup cols={2}>
  <Card title="Batch Processing" icon="layer-group">
    * Process up to 1,000 transfers per batch
    * Single API call for multiple transfers
    * Automatic validation of all entries
    * Bulk status tracking
  </Card>

  <Card title="Error Handling" icon="triangle-exclamation">
    * Individual transfer validation
    * Partial batch processing
    * Failed transfer retries
    * Detailed error reporting
  </Card>

  <Card title="Status Tracking" icon="chart-line">
    * Real-time batch status updates
    * Individual transfer tracking
    * Webhook notifications
    * Comprehensive reporting
  </Card>

  <Card title="Security Features" icon="shield-halved">
    * Transfer PIN protection
    * Multi-factor authentication
    * Fraud detection
    * Rate limiting
  </Card>
</CardGroup>

## Supported Transfer Types

<AccordionGroup>
  <Accordion title="Bank Transfers" icon="building-columns">
    **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
  </Accordion>

  <Accordion title="Crypto Transfers" icon="coins">
    **Supported Tokens**

    * USDT (TRX, ETH networks)
    * USDC (ETH, MATIC networks)

    **Features**

    * Multi-chain support
    * Gas fee optimization
    * Rate conversion
    * Automated confirmations
  </Accordion>

  <Accordion title="Interac e-Transfers" icon="money-bill-transfer">
    **Features**

    * Canadian bank support
    * Email/phone transfers
    * Auto-deposit capability
    * Real-time notifications

    **Requirements**

    * Canadian bank account
    * Valid email/phone
    * Account verification
  </Accordion>
</AccordionGroup>

## Batch Lifecycle

<Steps>
  <Step title="Creation">
    Initialize batch with basic details:

    * Batch reference
    * Description
    * Expiration time
  </Step>

  <Step title="Adding Transfers">
    Add transfers to the batch:

    * Beneficiary details
    * Transfer amounts
    * Payment references
    * Optional metadata
  </Step>

  <Step title="Validation">
    System validates:

    * Beneficiary information
    * Transfer limits
    * Available balance
    * Currency support
  </Step>

  <Step title="Execution">
    Process the batch:

    * PIN authorization
    * Transfer initiation
    * Status tracking
    * Webhook notifications
  </Step>

  <Step title="Completion">
    Final status updates:

    * Success counts
    * Failed transfers
    * Retry options
    * Detailed reporting
  </Step>
</Steps>

## 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

<Card>
  **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
</Card>

## Processing Times

<Info>
  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
</Info>

## 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

<CodeGroup>
  ```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);
  });
  ```
</CodeGroup>

<Card title="Next Steps">
  Learn how to:

  * [Initialize Bulk Transfers](/transfers/bulk-transfers/initiate-bulk-transfers)
  * [Add Transfers to Batch](/transfers/bulk-transfers/update-bulk-transfer)
  * [Execute Bulk Transfers](/transfers/bulk-transfers/execute-bulk-transfer)
  * [Monitor Transfer Status](/transfers/bulk-transfers/get-bulk-transfer-details)
</Card>