​
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.

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

​
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

StatusDescription
createdBatch initialized but not executed
executingTransfers being processed
completedAll transfers processed
cancelledBatch cancelled before execution
expiredBatch 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

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

// 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: "ben_123",
      description: "March Salary - John",
      reference: "salary-john-march"
    },
    // Add more transfers...
  ]
});

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