> ## Documentation Index
> Fetch the complete documentation index at: https://developer.me-cash.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Bulk Payouts
> Disburse funds to multiple beneficiaries in a single request for payroll, vendor payments, and mass disbursements.
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
```mermaid theme={null}
sequenceDiagram
participant Platform as Your Platform
participant MeCash as meCash API
Platform->>MeCash: 1. POST /v1/bulk/payout (orders + recipients)
activate MeCash
MeCash-->>Platform: Batch accepted (202)
deactivate MeCash
Note over MeCash,Platform: Asynchronous processing
Platform->>MeCash: 2. GET /v1/bulk/payout/{batchId}/status (Optional)
activate MeCash
MeCash-->>Platform: Batch results & aggregate counts
deactivate MeCash
MeCash-->>Platform: 3. Webhook per transfer (payout.completed / payout.failed)
```
## How it works
### Step 1: Submit bulk payout
Send all payout orders in one request to `POST /v1/bulk/payout`. Each item includes a unique `referenceNumber`, amount, reason, and full recipient bank details.
```bash cURL theme={null}
curl --location 'https://sandboxapi.me-cash.com/v1/bulk/payout' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY' \
--data '{
"items": [
{
"referenceNumber": "REF_ZZOEAZH8ZJI6",
"targetAmount": "1500",
"reason": "Salary payment",
"recipient": {
"name": "NNOROM UZOMA CHUKWUDI",
"account": {
"bankName": "FCMB",
"sortCode": "214",
"accountNumber": "2483520014"
},
"paymentChannel": "BANK_TRANSFER",
"currency": "NGN",
"country": "NG"
}
},
{
"referenceNumber": "REF_DZNGDNK5FFGH",
"targetAmount": "2500",
"reason": "Salary payment",
"recipient": {
"name": "NNOROM UZOMA CHUKWUDI",
"account": {
"bankName": "FCMB",
"sortCode": "214",
"accountNumber": "2483520014"
},
"paymentChannel": "BANK_TRANSFER",
"currency": "NGN",
"country": "NG"
}
},
{
"referenceNumber": "REF_YMSVIDEXJX1Y",
"targetAmount": "3600",
"reason": "Salary payment",
"recipient": {
"name": "NNOROM UZOMA CHUKWUDI",
"account": {
"bankName": "FCMB",
"sortCode": "214",
"accountNumber": "2483520014"
},
"paymentChannel": "BANK_TRANSFER",
"currency": "NGN",
"country": "NG"
}
}
],
"paymentChannel": "BANK_TRANSFER",
"remark": "June 2026 Salary"
}'
```
```json copy theme={null}
{
"message": "Batch Created",
"status": "success",
"data": {
"batchId": "44cbef79-3b95-4214-bda2-xxxxxxxxxxxx",
"referenceNo": "KJ5CFZ0YMWJC7",
"timestamp": "2026-04-08T17:35:54.114741545Z",
"batchTotal": 15,
"totalSuccessful": 0,
"totalFailed": 0,
"totalPending": 15
}
}
```
A `202 Accepted` response means the batch has been **queued** — not yet processed. Orders are settled asynchronously. Listen for [`payout.completed`](/webhook/payout-webhook) and [`payout.failed`](/webhook/payout-webhook) webhooks to track individual transfer outcomes.
### Step 2: Check batch status (Optional)
Poll for results using the `batchId` returned from Step 1. This is useful if you want to check overall progress without waiting for individual webhooks.
```bash cURL theme={null}
curl --location 'https://sandboxapi.me-cash.com/v1/bulk/payout/{{batchId}}/status' \
--header 'Content-Type: application/json' \
--header 'x-api-key: YOUR_API_KEY'
```
```json copy theme={null}
{
"message": "Transaction Processing",
"status": "success",
"data": {
"state": "pending",
"batchId": "44cbef79-3b95-4214-bda2-78014f400d11",
"startTimestamp": "2026-04-08T17:35:54.070396Z",
"endTimestamp": null,
"batchTotal": 15,
"totalSuccessful": 0,
"totalFailed": 0,
"totalPending": 15,
"items": [
{
"referenceNumber": "REF_ZZOEAZH8ZJI6",
"status": "pending",
"targetAmount": "1500",
"reason": "Salary payment",
"recipient": {
"id": "f55914fe-0568-473d-bf6f-95c32c71094e",
"name": "NNOROM UZOMA CHUKWUDI",
"account": {
"bankName": "FCMB",
"sortCode": "214",
"accountNumber": "2483520014"
},
"paymentChannel": "BANK_TRANSFER",
"currency": "NGN",
"country": "NG"
}
}
],
"paymentChannel": "BANK_TRANSFER",
"remark": "June 2026 Salary"
}
}
```
### Step 3: Listen for webhooks
Every individual payout in the batch triggers its own separate webhook — so a batch with 15 orders will fire **15 individual webhook events**. Each webhook is either [`payout.completed`](/webhook/payout-webhook) or [`payout.failed`](/webhook/payout-webhook), depending on the outcome of that specific transfer.
Use the `referenceNumber` from each order to correlate incoming webhook events with specific transfers in your system.
Your webhook endpoint must be able to handle **multiple concurrent deliveries**. For a large batch, many webhooks may arrive in quick succession as transfers are settled.
See [Webhook Signature Verification](/webhook/webhooks-signature-verification) to secure your endpoint.
## 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](/transaction-docs/get-transaction) 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
Disburse salaries to all employees in one API call instead of hundreds of individual transfers.
Pay multiple suppliers and vendors across different banks simultaneously.
Distribute commissions or rewards to agents, affiliates, or partners at once.
## Next steps
Full OpenAPI reference for `POST /v1/bulk/payout`.
Check processing status via `GET /v1/bulk/payout/{batchId}/status`.
Need to send to just one recipient? Use the standard payout flow.