Bulk Payouts

The meCash Bulk Payout API lets you disburse funds to multiple beneficiaries in a single API request. Instead of sending individual transfer requests, you submit a batch of payout orders — ideal for payroll, vendor payments, commissions, and mass disbursements.

Environment Note: The endpoints in this guide use the Sandbox URL (https://sandboxapi.me-cash.com). In Production, replace sandboxapi with api (https://api.me-cash.com).Each order within a bulk payout is processed independently. If one transfer fails validation, the remaining valid transfers still execute.

Bulk payout lifecycle

How it works

Request body breakdown

Field	Type	Required	Description
`items`	Array	✅	List of individual payout orders (see below).
`items[].referenceNumber`	String	✅	Your unique reference for this specific order.
`items[].targetAmount`	String	✅	Amount to send to the recipient.
`items[].reason`	String	✅	Purpose of the transfer (e.g. `Salary payment`).
`items[].recipient.name`	String	✅	Full name of the recipient.
`items[].recipient.account.bankName`	String	✅	Name of the recipient’s bank.
`items[].recipient.account.sortCode`	String	✅	Bank sort code / bank code.
`items[].recipient.account.accountNumber`	String	✅	Recipient’s bank account number.
`items[].recipient.paymentChannel`	String	✅	Payment method (e.g. `BANK_TRANSFER`).
`items[].recipient.currency`	String	✅	Target currency code (e.g. `NGN`).
`items[].recipient.country`	String	✅	Target country code (e.g. `NG`).
`paymentChannel`	String	✅	Top-level payment channel for the batch.
`remark`	String	❌	A general note for the entire batch submission.

Response breakdown

Field	Type	Description
`message`	String	Confirmation message from the API.
`status`	String	Overall request status (`success` or `failed`).
`data.state`	String	The processing state of the batch (e.g. `pending`, `completed`).
`data.batchId`	String	Unique identifier for the batch submission.
`data.startTimestamp`	String	ISO 8601 timestamp of when processing began.
`data.endTimestamp`	String	ISO 8601 timestamp of when processing finished (`null` if pending).
`data.batchTotal`	Number	Total number of payout orders in the batch.
`data.totalSuccessful`	Number	Total orders that have reached a final success state.
`data.totalFailed`	Number	Total orders that have failed processing.
`data.totalPending`	Number	Total orders still in the queue or being processed.
`data.items`	Array	A list of all individual payout orders and their specific statuses.

Key behaviors

Behavior	Description
Independent processing	Each transfer is validated and processed separately. A single failure does not block other orders.
Balance pre-check	The system validates that your wallet balance covers the total amount plus all fees before processing any orders.
Individual transaction records	Every order generates its own `referenceNumber`. Use the Get Transaction API to fetch full traceability details.
Rate limits	The bulk endpoint enforces payload size limits. Contact support for your account’s maximum orders per request.
Audit trail	Both the bulk request reference and individual transaction references are logged for compliance and reconciliation.

Use cases

Payroll

Disburse salaries to all employees in one API call instead of hundreds of individual transfers.

Vendor Payments

Pay multiple suppliers and vendors across different banks simultaneously.

Commission Payouts

Distribute commissions or rewards to agents, affiliates, or partners at once.

Next steps

Create Bulk Payout API

Full OpenAPI reference for POST /v1/bulk/payout.

Fetch Batch Status API

Check processing status via GET /v1/bulk/payout/{batchId}/status.

Single Payout Guide

Need to send to just one recipient? Use the standard payout flow.

Overview

Wallets

Quotes

Payouts

Virtual Accounts

Ramp

Transactions

Webhooks

Bulk payout lifecycle

How it works

Request body breakdown

Response breakdown

Key behaviors

Use cases

Payroll

Vendor Payments

Commission Payouts

Next steps

Create Bulk Payout API

Fetch Batch Status API

Single Payout Guide

​Bulk payout lifecycle

​How it works

​Request body breakdown

​Response breakdown

​Key behaviors

​Use cases

Payroll

Vendor Payments

Commission Payouts

​Next steps

Create Bulk Payout API

Fetch Batch Status API

Single Payout Guide

Bulk payout lifecycle

How it works

Request body breakdown

Response breakdown

Key behaviors

Use cases

Next steps