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.

☝️
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	Required - A unique reference for the bulk payout. This reference should have a length between 5 and 50 characters.
description	String	Optional
merchant_bears_cost	Boolean	Optional - 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`.
currency	String	Required - This is the currency of the transactions. E.g. `NGN`.
payouts	Array [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.
payout	Object	Required - This will capture how each object in the array of payouts will look like.
payout.reference	String	Required - A unique reference passed for the individual payout. This reference should have a length between 5 and 50 characters.
payout.amount	Number	Required - This is the transaction amount in two decimal places.
payout.type	String	Required - This value accepted is `bank_account`.
payout.narration	String	Required - This is the transaction's narration.
payout.bank_account	Object	Required - This captures the details of the receiving bank account for the payout
payout.bank_account.bank_code	String	Required - 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_number	String	Required - This is recipient's account number.
payout.customer	Object	Required - This captures the details of the customer.
payout.customer.name	String	Required - This is the name of the customer.
payout.customer.email	String	Required - 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
    }
}