Cancel Bulk Transfer

Overview

The Cancel Bulk Transfer endpoint allows you to stop a pending bulk transfer from being processed. You can cancel the entire batch or specific transfers within it, depending on their current status.

Only bulk transfers in created or executing status can be cancelled. Completed, expired, or already cancelled transfers cannot be modified.

Endpoint

POST /bulk-transfers/{id}/cancel

Path Parameters

string

required

The unique identifier of the bulk transfer to cancel

Request Example

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

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

import requests

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

Response Examples

{
  "data": {
    "created_at": "2024-10-02T17:39:26.049258",
    "description": "Monthly Vendor Payments",
    "expires_at": "2024-10-03T17:39:25Z",
    "failed_transfer_count": 0,
    "id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
    "items": [],
    "metadata": {},
    "owner": {
      "id": "65fb1bf9-10e7-4556-8005-0c3249b8df36",
      "type": "personal"
    },
    "reference": "46f3ef38-22de-4498-a6d3-13749aa2a0a7",
    "status": "cancelled",
    "successful_transfer_count": 0,
    "total_transfer_count": 0,
    "updated_at": "2024-10-02T17:39:26Z"
  }
}

{
  "error": {
    "code": "bulk_transfer_not_found",
    "message": "No bulk transfer found with ID: 7d528558-1c20-4bb6-9a9a-a03c8292b297"
  }
}

{
  "error": {
    "code": "invalid_state",
    "message": "Bulk transfer cannot be cancelled in its current state"
  }
}

Status Transitions

When you cancel a bulk transfer:

Status changes from created/executing to cancelled
All pending transfers are marked as cancelled
In-progress transfers complete normally
Completed transfers remain unchanged

Webhook Events

Monitor these events for cancellation status:

bulk_transfer.cancelled

Fired when the bulk transfer is successfully cancelled

{
  "event": "bulk_transfer.cancelled",
  "data": {
    "id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
    "status": "cancelled",
    "cancelled_at": "2024-10-02T18:00:00Z",
    "cancelled_transfers": 5,
    "completed_transfers": 2
  }
}

bulk_transfer.transfer.cancelled

Fired for each cancelled transfer in the batch

{
  "event": "bulk_transfer.transfer.cancelled",
  "data": {
    "bulk_transfer_id": "7d528558-1c20-4bb6-9a9a-a03c8292b297",
    "transfer_id": "tr_123abc",
    "status": "cancelled",
    "cancelled_at": "2024-10-02T18:00:00Z"
  }
}

Error Handling

error

The specified bulk transfer doesn’t exist

Verify the bulk transfer ID
Check the ID format

error

Transfer cannot be cancelled in current state

Only created/executing transfers can be cancelled
Check current transfer status

error

Some transfers could not be cancelled

In-progress transfers will complete
Check individual transfer statuses

Refund Handling

For transfers that require refunds:

Successfully cancelled transfers are automatically reversed
Funds are returned to your balance
Refund status is tracked via webhooks
Processing time varies by payment method

Some payment methods may have specific refund restrictions or processing times.

Best Practices

Pre-cancellation Checks
- Verify bulk transfer status
- Check for in-progress transfers
- Consider timing of cancellation
Monitoring
- Implement webhook handling
- Track cancellation status
- Monitor refund processing
Error Handling
- Handle partial cancellations
- Implement retry logic
- Log cancellation attempts

Need Help?

For additional assistance:

Home

Customers

Payments

Payment Transactions

Transfers

Exchange

Wallet As A Service

Overview

Endpoint

Path Parameters

Request Example

Response Examples

Status Transitions

Webhook Events

Error Handling

Refund Handling

Best Practices

Need Help?

​Overview

​Endpoint

​Path Parameters

​Request Example

​Response Examples

​Status Transitions

​Webhook Events

​Error Handling

​Refund Handling

​Best Practices

Need Help?

Overview

Endpoint

Path Parameters

Request Example

Response Examples

Status Transitions

Webhook Events

Error Handling

Refund Handling

Best Practices