Bulk Transfer
Send money to multiple recipients in one go using Chapa's bulk transfers API
You can send money to multiple recipients in one go using the Chapa's bulk transfers API.
How to make a bulk payment
To do this, you'll provide an array of objects called bulk_data. Each item in this array contains details for one transfer—the same details you specify when making a single transfer.
You can also specify a title for the transfer. This is helpful so you can easily identify what a set of payments was for.
Keep in Mind: Each object in the bulk_data array is the same parameters for a single transfer request. A batch should not contain more than 100 items and each batch should be sent every 5 seconds. The duration is to avoid getting rate limited. Sending multiple requests at short intervals would lead to a 429 (Too many requests) error.
With your batch properly planned and implemented, you can now initiate the bulk transfer.
Endpoint: https://api.chapa.co/v1/bulk-transfers
Method: POST
Authorization: Pass your secret key as a bearer token in the request header to authorize this call.
Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
title | No | string | Title for the bulk transfer (helpful for identification) |
currency | Yes | string | The currency for all transfers (ETB) |
bulk_data | Yes | array | Array of transfer objects (max 100 items) |
account_name | Yes | string | Recipient account name (within each bulk_data item) |
account_number | Yes | string | Recipient account number (within each bulk_data item) |
amount | Yes | number | Transfer amount (within each bulk_data item) |
reference | No | string | Unique reference for this transfer (within each bulk_data item) |
bank_code | Yes | number | Bank code (within each bulk_data item). See Bank List for codes |
Successful Response
{
"message": "Bulk transfer queued successfully",
"status": "success",
"data": {
"id": 4,
"created_at": "2024-03-20T08:56:24.000000Z"
}
}The transfers will be queued for processing, which usually take between a few seconds.
Failed Response
{
"message": {
"bulk_data.1.amount": [
"The amount field is required"
]
},
"status": "failed"
}Refer to our Error Codes page for all responses for this request.
Checking the status
You can also check the status of a bulk transfer manually using the get all transfers endpoint with a batch_id query parameter. The batch_id is the data.id returned from the create bulk transfer response.
Endpoint: https://api.chapa.co/v1/transfers?batch_id={id}
Method: GET
Authorization: Pass your secret key as a bearer token in the request header to authorize this call.
Example Request
import requests
url = "https://api.chapa.co/v1/transfers?batch_id=1"
payload = ""
headers = {
'Authorization': 'Bearer CHASECK-xxxxxxxxxxxxxxxx'
}
response = requests.request("GET", url, headers=headers, data=payload)
print(response.text)Successful Response
{
"message": "Transfer details fetched",
"status": "success",
"meta": {
"current_page": 1,
"first_page_url": "https://api.chapa.co/v1/transfers?page=1",
"last_page": 1,
"last_page_url": "https://api.chapa.co/v1/transfers?page=1",
"next_page_url": null,
"path": "https://api.chapa.co/v1/transfers?page=1",
"per_page": 10,
"prev_page_url": null,
"to": 2,
"total": 2,
"error": []
},
"data": [
{
"account_name": "Israel Goytom",
"account_number": null,
"currency": "ETB",
"amount": 1,
"charge": 0,
"transfer_type": "wallet",
"chapa_reference": "smtlsmH436t6",
"bank_code": 128,
"bank_name": "telebirr",
"bank_reference": "BCJ8FVX8AG",
"status": "success",
"reference": "b2222e5r",
"created_at": "2024-03-19T20:05:45.000000Z",
"updated_at": "2024-03-19T20:06:10.000000Z"
},
{
"account_name": "Israel Goytom",
"account_number": null,
"currency": "ETB",
"amount": 1,
"charge": 0,
"transfer_type": "wallet",
"chapa_reference": "VjYYS6TguXaL",
"bank_code": 128,
"bank_name": "telebirr",
"bank_reference": "BCJ0FVX87Q",
"status": "success",
"reference": "b1111124",
"created_at": "2024-03-19T20:05:45.000000Z",
"updated_at": "2024-03-19T20:06:06.000000Z"
}
]
}Failed Response
{
"status": "failed",
"message": "The Endpoint you are looking for is not found. Please refer to our documentation for more. developer.chapa.co"
}Best Practices
- Batch Size: Keep batches under 100 items to avoid errors
- Rate Limiting: Wait at least 5 seconds between batch requests
- Validation: Validate all account details before including them in bulk_data
- References: Use unique references for each transfer in the batch for easier tracking
- Error Handling: Check individual transfer statuses using the batch_id query parameter
Next Steps
- Transfer - Make a single transfer
- Verify Transfer - Verify individual transfer status
- All Transfers - View all your transfers
- Bank List - Get list of available banks and their codes
- Error Codes - Handle errors gracefully