Initiate Bulk Transfer

Overview

Bulk transfers allow you to process multiple transfers in a single batch operation. This endpoint creates a new bulk transfer session that you can later populate with individual transfers and execute as a group.

Before initiating a bulk transfer:

Ensure sufficient balance for the expected total
Have your beneficiary details ready
Review the transfer limits and cut-off times

Endpoint

POST /bulk-transfers

Request Parameters

string

Maximum length: 200 characters
Used for reference and reporting

string

Timestamp when the bulk transfer session expires

Format: ISO 8601 (e.g., “2024-10-03T18:38:31Z”)
Maximum: 72 hours from creation
Default: 24 hours from creation

string

required

Your unique reference for this bulk transfer

Must be unique across all bulk transfers
Maximum length: 64 characters
Alphanumeric characters, hyphens, and underscores only

object

Additional data about the bulk transfer

Maximum size: 20KB
Key-value pairs of strings

Request Examples

{
  "description": "Monthly vendor payments",
  "expires_at": "2024-10-03T18:38:31Z",
  "reference": "juice-bulk-transfer-5d906f6d-933b-4de9-927f-c7522823f5ec"
}

{
  "description": "Q4 contractor payments",
  "expires_at": "2024-10-03T18:38:31Z",
  "reference": "juice-bulk-q4-contractors-2024",
  "metadata": {
    "department": "engineering",
    "batch_type": "contractors",
    "period": "Q4-2024"
  }
}

Response Format

object

Created bulk transfer session details

Show Response Fields

string

Unique identifier for the bulk transfer

string

Creation timestamp in ISO 8601 format

string

Expiration timestamp in ISO 8601 format

string

Provided description

string

Current status of the bulk transfer:

created - Initial state
executing - Transfers in progress
completed - All transfers processed
cancelled - Manually cancelled
expired - Session timeout

integer

Number of failed transfers in the batch

integer

Number of successful transfers in the batch

integer

Total number of transfers in the batch

array

List of individual transfers (empty on creation)

object

Additional metadata provided

object

Details about the creating entity

Response Examples

{
  "data": {
    "created_at": "2024-10-02T17:39:26.049258Z",
    "description": "Monthly vendor payments",
    "expires_at": "2024-10-03T18:38:31Z",
    "failed_transfer_count": 0,
    "id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
    "items": [],
    "metadata": {},
    "owner": {
      "id": "65fb1bf9-10e7-4556-8005-0c3249b8df36",
      "type": "personal"
    },
    "reference": "juice-bulk-transfer-5d906f6d-933b-4de9-927f-c7522823f5ec",
    "status": "created",
    "successful_transfer_count": 0,
    "total_transfer_count": 0,
    "updated_at": "2024-10-02T17:39:26Z"
  }
}

{
  "error": {
    "code": "invalid_request",
    "message": "The request contains invalid parameters",
    "details": {
      "reference": ["Must be unique across all bulk transfers"]
    }
  }
}

{
  "error": {
    "code": "validation_error",
    "message": "Invalid expiration time",
    "details": {
      "expires_at": ["Must be between 1 and 72 hours from now"]
    }
  }
}

Validation Rules

Reference Rules

Must be unique across all bulk transfers
Length: 1-64 characters
Allowed characters: A-Z, a-z, 0-9, -, _
Cannot start or end with hyphen/underscore

Expiration Rules

Must be in future
Minimum: 1 hour from creation
Maximum: 72 hours from creation
Must be valid ISO 8601 format

Description Rules

Maximum length: 200 characters
Cannot contain HTML or special characters
Optional but recommended for tracking

Metadata Rules

Maximum size: 20KB
Keys must be strings
Values must be strings
No nested objects allowed

Rate Limits

10 bulk transfer initiations per minute
Maximum of 100 transfers per batch
Burst limit: 2 requests per second

Best Practices

Reference Generation
- Use structured, meaningful references
- Include date/time components
- Add batch type identifiers
- Store references for reconciliation
Error Handling
- Implement proper retry logic
- Monitor rate limits
- Log all attempts
- Handle timeouts gracefully
Session Management
- Set reasonable expiration times
- Plan for session timeouts
- Monitor session status
- Handle expired sessions

Next Steps

After creating a bulk transfer session:

Home

Customers

Payments

Payment Transactions

Transfers

Exchange

Wallet As A Service

Overview

Endpoint

Request Parameters

Request Examples

Response Format

Response Examples

Validation Rules

Rate Limits

Best Practices

Next Steps

​Overview

​Endpoint

​Request Parameters

​Request Examples

​Response Format

​Response Examples

​Validation Rules

​Rate Limits

​Best Practices

Next Steps

Overview

Endpoint

Request Parameters

Request Examples

Response Format

Response Examples

Validation Rules

Rate Limits

Best Practices