Bulk Payouts via API
Similar to making a single payout to a bank account via API, you can also use our API to make payouts to multiple bank accounts.
When you initiate a bulk payout request, the disbursement is made from your balance. We send a webhook notification after each individual payout in the batch is completed. In addition, we send an email notification when the bulk payout is initiated, and another when it is complete.
Currently, Kora’s Bulk Payout API supports Payouts to:
- Nigerian (NGN) bank accounts
- Kenyan (KES) Mobile money accounts
- South African (ZAR) bank accounts
- Ghanaian (GHS) Mobile Money accounts
Before initiating a bulk payout, always ensure that there are sufficient funds in your balance to cover it.
Similar to a payout to a single bank account, you can also retrieve the status of each payout in a batch using our verify API or through the dashboard.
The endpoint to call when initiating a bulk payout is:
{{baseurl}}/api/v1/transactions/disburse/bulk
The request body should include:
Field | Data Type | Description |
---|---|---|
batch_reference | String |
|
description | String | Optional |
merchant_bears_cost | Boolean |
|
currency | String |
|
payouts | Array [Object] |
|
payout | Object |
|
payout.reference | String |
|
payout.amount | Number |
|
payout.type | String |
|
payout.narration | String |
|
payout.bank_account | Object |
|
payout.bank_account.bank_code | String |
See the bank details for other test scenarios here. |
payout.bank_account.account_number | String |
|
payout.customer | Object |
|
payout.customer.name | String |
|
payout.customer.email | String |
|
Here’s how the response for your payout request should look like:
{
"status": true,
"message": "Bulk Transfer initiated successfully",
"data": {
"status": "pending",
"total_chargeable_amount": 1000,
"merchant_bears_cost": false,
"reference": "Batch-Reference-01",
"currency": "NGN",
"description": "test bulk transfer",
"createdAt": "2023-04-10TI7:38:42.521Z",
}
}
Fetch Bulk Payout
You can fetch an initiated bulk payout with the following endpoint. It also returns the status of the bulk payout which could be pending
, failed
, or complete
.
{{baseurl}}/api/v1/transactions/bulk/:batch_reference
The response to this could look like:
{
"status": true,
"message": "Bulk transaction retrieved successfully",
"data": {
"amount": "3500.00",
"currency": "NGN",
"reference": "batch_reference",
"status": "complete",
"description": "test bulk transfer",
"failedTransactions": 1,
"successfulTransactions": 1,
"pendingTransactions": 0,
"processingTransactions": 0
}
}
Fetch all Payouts in the Batch
You can also fetch all the payouts in a batch with the following endpoint. It returns an array of payouts.
{{baseurl}}/api/v1/transactions/bulk/:batch_reference/payouts
An example of a response could look like this:
{
"status": true,
"message": "Payouts retrieved successfully",
"data": {
"data": [
{
"reference": "001_Reference",
"amount": 1000,
"currency": "NGN",
"narration": "Test transfer to F4B Developers",
"status": "success",
"batch_reference": "Test_Bulk_reference",
"type": "bank_account",
"customer": {
"name": "Test User 1",
"email": "[email protected]"
},
"bank_account": {
"bank_code": "044",
"account_number": "0000000000"
}
},
{
"reference": "002_Reference",
"amount": 1200,
"currency": "NGN",
"narration": "Test transfer to F4B Developers",
"status": "success",
"batch_reference": "Test_Bulk_reference",
"type": "bank_account",
"customer": {
"name": "Test User 2",
"email": "[email protected]"
},
"bank_account": {
"bank_code": "044",
"account_number": "0000000000"
}
},
{
"reference": "003_Reference",
"amount": 1300,
"currency": "NGN",
"narration": "Test transfer to F4B Developers",
"status": "success",
"batch_reference": "Test_Bulk_reference_S",
"type": "bank_account",
"customer": {
"name": "Test User 3",
"email": "[email protected]"
},
"bank_account": {
"bank_code": "044",
"account_number": "0000000000"
}
},
],
"paging": {
"total_items": 3,
"page_size": 10,
"current": 1,
"count": 3
},
}
}
Fetch Payout Transaction
You can fetch a single payout in a batch by their reference with the following endpoint.
{{baseurl}}/api/v1/transactions/:reference
If the payout was successful, you would get a response that could look like this:
{
"status": true,
"message": "Transaction retrieved successfully",
"data": {
"reference": "001_payout_reference",
"batch_reference": "batch_reference",
"status": "success",
"amount": 1000,
"fee": 15.31,
"currency": "NGN",
"narration": "Test transfer to Test User",
"trace_id": "521853970021533363527535291465",
"message": "Payout successful",
"customer": {
"email": "[email protected]",
"name": "Test User"
},
"metadata": null
}
}
And if the payout failed, you would get a response that could look like this:
{
"status": true,
"message": "Transaction retrieved successfully",
"data": {
"reference": "001_payout_reference",
"batch_reference": "batch_reference",
"status": "failed",
"amount": 1000.00,
"fee": 15.31,
"currency": "NGN",
"narration": "Test transfer to Test user",
"message": "Invalid Bank Account",
"customer": {
"email": "[email protected]",
"name": "Test User"
},
"metadata": null
}
}
Updated about 1 month ago