Bulk Transfer
A bulk transfer is a collection or an array of individual transfers. Similar to making a single transfer via API, you can use our Bulk Transfer API endpoint to make multiple transfers to with one API request.
This can be useful for transferring large amounts of funds or for making multiple transfers to recipients.
A bulk transfer request can consist of any of the following:
A. Multiple Book Transfers (Book Transfer)
- Multiple book transfers from one source account to different recipients
- Multiple book transfers from different source accounts to different recipients
- Multiple book transfers from different source accounts to one recipient
B. Multiple Bank Transfers (NIP Transfer)
- Multiple book transfers from one source account to different recipients
- Multiple book transfers from different source accounts to different recipients
- Multiple book transfers from different source accounts to one recipient
C. Combination of Book Transfer and Bank Transfer
You can send up to hundred (100) single transfers in on single bulk transfer request
When you initiate a bulk transfer, all the individual transfers in the bulk transfer are processed individually. This means that a record is created for all the individual transfers in the bulk transfer request.
We use a queuing system to ensure that all the transfers are handled appropriately.
Initiate Bulk Transfer
Verb | URL |
---|---|
POST | {{baseUrl}}/api/v1/transfers/bulk |
The transfers
array can contain up to 100 single transfers. Each transfer object must have the following properties:
amount
: The amount of the transfer specified in the smallest unit of the currency.currency
: The currency of the transfer eg NGNreason
: The Reason specifies the purpose or motivation behind the transfer, such as "Payment," "Refund," or "Salary."reference
: Reference allows for including additional information or notes related to the transfer, facilitating easy identification and context.relationships
: A JSON object with the following object:account
: The source account object.destinationAccount
: The recipient's account object.
Sample Bulk Transfer Request Payload
curl --request POST \
--url https://api.sandbox.getanchor.co/api/v1/transfers/bulk \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--header 'x-anchor-key: <API Key>' \
--data '
{
"data": [
{
"attributes": {
"currency": "NGN",
"amount": 10000,
"reason": "test bulk transfer 1",
"reference": "bulkanc_ref1001"
},
"relationships": {
"account": {
"data": {
"type": "DepositAccount",
"id": "16922123754372-anc_acc"
}
},
"destinationAccount": {
"data": {
"type": "DepositAccount",
"id": "169925847367121-anc_acc"
}
}
},
"type": "BOOK_TRANSFER"
},
{
"attributes": {
"currency": "NGN",
"amount": 10000,
"reason": "fail test bulk transfer 3",
"reference": "bulkanc_ref1003"
},
"relationships": {
"account": {
"data": {
"type": "DepositAccount",
"id": "16922123754372-anc_acc"
}
},
"destinationAccount": {
"data": {
"type": "DepositAccount",
"id": "169925847367121-anc_acc"
}
}
},
"type": "BOOK_TRANSFER"
},
{
"attributes": {
"currency": "NGN",
"amount": 10000,
"reason": "fail test bulk transfer 5",
"reference": "bulkanc_ref1005"
},
"relationships": {
"account": {
"data": {
"type": "DepositAccount",
"id": "16922123754372-anc_acc"
}
},
"destinationAccount": {
"data": {
"type": "DepositAccount",
"id": "169925847367121-anc_acc"
}
}
},
"type": "BOOK_TRANSFER"
},
{
"attributes": {
"currency": "NGN",
"amount": 1200,
"reference": "bulkanc_ref1002",
"reason": "test bulk transfer 2"
},
"relationships": {
"account": {
"data": {
"type": "DepositAccount",
"id": "16922123754372-anc_acc"
}
},
"destinationAccount": {
"data": {
"type": "SubAccount"
}
},
"counterParty": {
"data": {
"type": "CounterParty",
"id": "169558397056513-anc_cp"
}
}
},
"type": "NIP_TRANSFER"
},
{
"attributes": {
"currency": "NGN",
"amount": 10000,
"reason": "test bulk transfer 4",
"reference": "bulkanc_ref1004"
},
"relationships": {
"account": {
"data": {
"type": "DepositAccount",
"id": "16922123754372-anc_acc"
}
},
"destinationAccount": {
"data": {
"type": "DepositAccount",
"id": "169925847367121-anc_acc"
}
}
},
"type": "BOOK_TRANSFER"
},
{
"attributes": {
"currency": "NGN",
"amount": 10000,
"reason": "test bulk transfer 6",
"reference": "bulkanc_ref1006"
},
"relationships": {
"account": {
"data": {
"type": "DepositAccount",
"id": "16922123754372-anc_acc"
}
},
"destinationAccount": {
"data": {
"type": "DepositAccount",
"id": "169925847367121-anc_acc"
}
}
},
"type": "BOOK_TRANSFER"
}
]
}
'
Sample 200 OK Response
{
"data": {
"id": "17001292261573-anc_bk_trsf",
"type": "BulkTransfer",
"attributes": {
"requeryTransferCount": 0,
"createdAt": "2023-11-16T10:07:06.159098",
"amount": 51200,
"totalTransferCount": 6,
"currency": "NGN",
"successfulTransferCount": 0,
"failedTransferCount": 0,
"status": "PENDING"
},
"relationships": {
"transfers": {
"data": []
}
}
}
}
How are Webhooks Sent for Bulk Transfers?
- When a bulk transfer is performed, we send
bulkTransfer.started
andbulkTransfer.completed
events. - You can use the supportIncluded functionality to fetch additional information in a
bulkTransfer.completed
event. Note thatbulkTransfer.completed
does not imply that all the payments were successful. It just means each of transfers have reach a final state which can be successful or failed. - In addition to the above events, we send webhooks related to the individual transfer in the bulk transfer such as
book.transfer.initiated
andbook.transfer.successful
for a book transfer in the bulk transfer andnip.transfer.initiated
andnip.transfer.successful
for an bank transfer (NIP_Transfer) in the in the bulk transfer.
Rate Limiting
To ensure fair usage, the Bulk Transfer API has rate limiting in place. If you exceed the allowed number of requests, you will receive a 429 Too Many Requests
response.
Fetch Bulk Transfer
Similar to a single transfer, you can also fetch the status of a bulk transfer using our Fetch Bulk Transfer API.
Verb | URL |
---|---|
GET | {{baseUrl}}/api/v1/transfers/bulk/{bulkTransferId} |
Sample Request to Fetch a Bulk Transfer:
curl --request GET \
--url https://api.sandbox.getanchor.co/api/v1/transfers/bulk/17001247383540-anc_bk_trsf \
--header 'accept: application/json' \
--header 'x-anchor-key: <API Key>'
{
"data": {
"id": "17001247383540-anc_bk_trsf",
"type": "BulkTransfer",
"attributes": {
"requeryTransferCount": 0,
"createdAt": "2023-11-16T08:52:18",
"amount": 11200,
"totalTransferCount": 2,
"currency": "NGN",
"successfulTransferCount": 2,
"failedTransferCount": 0,
"status": "COMPLETED"
},
"relationships": {
"transfers": {
"data": [
{
"id": "1700124740883223-anc_trsf",
"type": "NIP_TRANSFER"
},
{
"id": "1700124740724222-anc_trsf",
"type": "BOOK_TRANSFER"
}
]
}
}
}
}
Updated about 1 month ago