Bulk payout

Allows a merchant to initiate multiple bank payouts by uploading a CSV file containing recipient account details and payout amounts.

The endpoint supports up to 1,000 bank accounts per batch.

Before uploading the CSV file, ensure that the merchant's wallet has sufficient funds to cover the payout batch. An upload fails when there is insufficient balance.

Endpoint

POST /api/v1/payout/wallet-bank/upload

Authorization

Bearer Token

A valid Bearer Token is required to authenticate the request.

Headers

Header	Description	Required
`Authorization`	Bearer token used to authenticate the request	Yes
`Content-Type`	Must be `multipart/form-data` because a CSV file is uploaded	Yes
`x-merchant-ref`	Unique reference identifying the merchant	Yes

Form Data

Field	Description	Required
`csv_file`	CSV file containing the bank payout records	Yes
`batch_id`	Unique identifier for the payout batch	Yes
`currency`	Currency of the payout batch, for example `NGN`	Yes
`user_ref`	Reference of the user initiating the payout batch	Yes

CSV Format

The uploaded CSV file must contain three columns in the following order: see sample template

Account number	Bank code	Amount
8062551122	100004	1000

Each subsequent row represents one bank payout.

Upload Limits

Maximum of 1,000 bank accounts per batch.
The first CSV row is skipped.
The CSV must contain exactly three columns in the required order.
The merchant wallet must have sufficient balance before uploading the batch.

Request

curl --location -g '{{base_url}}/api/v1/payout/wallet-bank/upload' \
--header 'Authorization: Bearer <token>' \
--header 'x-merchant-ref: {{vault:x-merchant-ref}}' \
--form 'csv_file=@"/path/to/payouts.csv"' \
--form 'batch_id="BATCH_TEST_001"' \
--form 'currency="NGN"' \
--form 'user_ref="USR_TEST_005"'

Response

A successful upload returns a LedgerBlock batch reference.

The batch reference can be used to identify and track the uploaded payout batch.

Insufficient Balance

The merchant's wallet must be sufficiently funded before uploading the CSV.

If the merchant does not have enough balance to process the batch, the upload fails with an INSUFFICIENT BALANCE condition.

Important: Fund the merchant wallet before submitting a bulk payout batch.

How It Works

Prepare the CSV using the required three-column format.
Add the bank account number, bank code, and payout amount for each recipient.
Ensure the first row contains headers.
Ensure the batch contains no more than 1,000 bank accounts.
Ensure the merchant wallet has sufficient funds.
Submit the CSV together with the batch_id, currency, and user_ref.
LedgerBlock validates the upload.
If the upload is successful, LedgerBlock returns a batch reference for the payout batch.

Use Cases

Bulk Payout can be used to:

Pay multiple bank accounts in a single batch.
Process payroll or supplier payments.
Process large sets of customer payouts.
Upload up to 1,000 bank accounts per batch.
Track a group of payouts using a single batch reference.

Note: All user references, batch IDs, account numbers, bank codes, and other example values above are dummy data for documentation purposes. Replace them with your actual values when making API requests.