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 NGN
reason: 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 and bulkTransfer.completed events.
You can use the supportIncluded functionality to fetch additional information in a bulkTransfer.completed event. Note that bulkTransfer.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 and book.transfer.successful for a book transfer in the bulk transfer and nip.transfer.initiated and nip.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"
          }
        ]
      }
    }
  }
}

📘You can send up to hundred (100) single transfers in on single bulk transfer request

Initiate Bulk Transfer

How are Webhooks Sent for Bulk Transfers?

Rate Limiting

Fetch Bulk Transfer

📘
You can send up to hundred (100) single transfers in on single bulk transfer request