Execute Bulk Transfer

Overview

The Execute Bulk Transfer endpoint initiates the processing of all transfers within a prepared bulk transfer batch. This operation transitions the bulk transfer from created status to executing and begins processing individual transfers.

Before executing a bulk transfer:

Ensure all transfer details are correct
Verify sufficient balance for all transfers
Check that the bulk transfer hasn’t expired
Confirm no validation errors in transfer items

Endpoint

POST /bulk-transfers/{id}/execute

Path Parameters

string

required

The unique identifier of the bulk transfer to execute

Must be in created status
Must not be expired
Must have at least one valid transfer

Prerequisites

Before execution can begin:

All transfers must have valid beneficiary details
Total transfer amount must not exceed your limits
Your account must have sufficient balance
The bulk transfer must not be expired
No pending validation issues

Example Request

curl -X POST "https://api.spendjuice.com/bulk-transfers/7d528558-1c20-4bb6-9a9a-a03c8292b297/execute" \
-H "Authorization:  YOUR_API_KEY" \
-H "Content-Type: application/json"

const response = await fetch(
  'https://api.spendjuice.com/bulk-transfers/7d528558-1c20-4bb6-9a9a-a03c8292b297/execute',
  {
    method: 'POST',
    headers: {
      'Authorization': ' YOUR_API_KEY',
      'Content-Type': 'application/json'
    }
  }
);

import requests

response = requests.post(
    'https://api.spendjuice.com/bulk-transfers/7d528558-1c20-4bb6-9a9a-a03c8292b297/execute',
    headers={
        'Authorization': ' YOUR_API_KEY',
        'Content-Type': 'application/json'
    }
)

Response Format

Success Response (202 Accepted)

{
  "data": {
    "id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
    "status": "executing",
    "total_transfer_count": 10,
    "successful_transfer_count": 0,
    "failed_transfer_count": 0,
    "created_at": "2024-03-15T10:30:00Z",
    "updated_at": "2024-03-15T10:35:00Z",
    "execution_started_at": "2024-03-15T10:35:00Z"
  }
}

Status Transitions

When a bulk transfer is executed, it goes through these status changes:

created → executing

Initial transition when execution begins

executing → completed

All transfers processed successfully

executing → partially_completed

Some transfers succeeded, some failed

executing → failed

All transfers failed to process

Webhook Events

Monitor these webhook events for bulk transfer status:

bulk_transfer.executing

Triggered when execution begins

{
  "event": "bulk_transfer.executing",
  "data": {
    "id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
    "status": "executing",
    "total_transfer_count": 10
  }
}

bulk_transfer.completed

Triggered when all transfers complete successfully

{
  "event": "bulk_transfer.completed",
  "data": {
    "id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
    "status": "completed",
    "successful_transfer_count": 10,
    "failed_transfer_count": 0
  }
}

bulk_transfer.failed

Triggered if execution fails

{
  "event": "bulk_transfer.failed",
  "data": {
    "id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
    "status": "failed",
    "error": {
      "code": "insufficient_balance",
      "message": "Insufficient balance for transfer"
    }
  }
}

Error Handling

error

Bulk transfer is not in executable state

Status code: 400
Must be in created status

error

Insufficient balance for transfers

Status code: 400
Check available balance

error

Bulk transfer has expired

Status code: 400
Create new bulk transfer

error

One or more transfers invalid

Status code: 422
Fix validation issues first

Rate Limits

Bulk transfer execution is subject to these limits:

Maximum 1 execution request per bulk transfer
Maximum 100 transfers per bulk transfer
Maximum 10 concurrent executing bulk transfers

Best Practices

Pre-execution Validation
- Verify all beneficiary details
- Check sufficient balance
- Validate transfer amounts
- Monitor expiration time
Error Handling
- Implement webhook handling
- Monitor individual transfer status
- Handle partial completions
- Log execution attempts
Monitoring
- Track execution progress
- Monitor success rates
- Set up alerts for failures
- Review execution logs

Need Help?

For additional assistance:

Check our Webhooks Guide
Review Error Handling
Contact Support

Home

Customers

Payments

Payment Transactions

Transfers

Exchange

Wallet As A Service

Overview

Endpoint

Path Parameters

Prerequisites

Example Request

Response Format

Success Response (202 Accepted)

Status Transitions

Webhook Events

Error Handling

Rate Limits

Best Practices

Need Help?

​Overview

​Endpoint

​Path Parameters

​Prerequisites

​Example Request

​Response Format

​Success Response (202 Accepted)

​Status Transitions

​Webhook Events

​Error Handling

​Rate Limits

​Best Practices

Need Help?

Overview

Endpoint

Path Parameters

Prerequisites

Example Request

Response Format

Success Response (202 Accepted)

Status Transitions

Webhook Events

Error Handling

Rate Limits

Best Practices