Skip to main content

​
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

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
Supported Tokens
  • USDT (TRX, ETH networks)
  • USDC (ETH, MATIC networks)
Features
  • Multi-chain support
  • Gas fee optimization
  • Rate conversion
  • Automated confirmations
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

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

    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);