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:

FieldData TypeDescription
batch_referenceStringRequired - A unique reference for the bulk payout. This reference should have a length between 5 and 50 characters.
descriptionStringOptional
merchant_bears_costBooleanOptional - This will set who bears the fees of the transactions. If it is set to true, the merchant will bear the fee, while if it is set to false, the customer will bear the fee. By default, it is false.
currencyStringRequired - This is the currency of the transactions. E.g. NGN, KES, GHS, ZAR.
payoutsArray [Object]Required - This captures all the payouts in the batch. A minimum of 2 and a maximum of 50 payouts are allowed in a batch.
payoutObjectRequired - This will capture how each object in the array of payouts will look like.
payout.referenceStringRequired - A unique reference passed for the individual payout. This reference should have a length between 5 and 50 characters.
payout.amountNumberRequired - This is the transaction amount in two decimal places.
payout.typeStringRequired - This value accepted is bank_account.
payout.narrationStringRequired - This is the transaction's narration.
payout.bank_accountObjectRequired - This captures the details of the receiving bank account for the payout
payout.bank_account.bank_codeStringRequired - This is the recipient's bank code. Some bank codes that you can use to simulate successful transactions in test mode are 044, 033, 058 (i.e. for Access Bank, UBA and GTCO respectively).

See the bank details for other test scenarios here.
payout.bank_account.account_numberStringRequired - This is recipient's account number.
payout.customerObjectRequired - This captures the details of the customer.
payout.customer.nameStringRequired - This is the name of the customer.
payout.customer.emailStringRequired - This is the email of the customer.

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
    }
}