Skip to main content
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.
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

1
Step 1: Create a bulk quote
2
Send all transfer amounts in a single request to POST /v1/bulk/quote. Each item receives its own quoteId with independent pricing, fees, and expiry.
3
curl --request POST 'https://devapi.me-cash.com/v1/bulk/quote' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "paymentChannel": "BANK_TRANSFER",
    "items": [
        { "sourceAmount": 100.00 },
        { "sourceAmount": 250.50 }
    ],
    "source": { "currency": "NGN", "country": "NG" },
    "target": { "currency": "NGN", "country": "NG" }
}'
4
Step 2: Fetch quotes (optional)
5
Retrieve one or more quotes by their IDs to confirm pricing before executing. Pass multiple quoteIds as query parameters.
6
curl --request GET 'https://devapi.me-cash.com/v1/bulk/quote?quoteIds=fa01c1ad-6c0f-4074-8221-ffc8fdaa16db&quoteIds=6809b2ab-1d4d-4436-8218-46667419eee7' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY'
7
Step 3: Submit bulk payout
8
Send all payout orders in one request to POST /v1/bulk/payout. Each order pairs a quoteId with recipient bank details.
9
curl --request POST 'https://devapi.me-cash.com/v1/bulk/payout' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_API_KEY' \
  --data '{
    "orders": [
        {
            "quoteId": "b70f6798-ae5c-41fd-92c9-d6cfc325b8dc",
            "recipient": {
                "id": "a5b60e98-90b2-4fd6-95b6-13dadc51467f",
                "name": "NNOROM UZOMA CHUKWUDI",
                "account": {
                    "bankName": "FCMB",
                    "sortCode": "214",
                    "accountNumber": "2483520014"
                },
                "paymentChannel": "BANK_TRANSFER",
                "currency": "NGN",
                "country": "NG"
            },
            "remark": "payment 1",
            "reason": "Gift"
        },
        {
            "quoteId": "faeafe20-d5c8-47b5-913a-2c81d15a69cb",
            "recipient": {
                "id": "a5b60e98-90b2-4fd6-95b6-13dadc51467f",
                "name": "NNOROM UZOMA CHUKWUDI",
                "account": {
                    "bankName": "FCMB",
                    "sortCode": "214",
                    "accountNumber": "2483520014"
                },
                "paymentChannel": "BANK_TRANSFER",
                "currency": "NGN",
                "country": "NG"
            },
            "remark": "payment 2",
            "reason": "Gift"
        }
    ]
}'
10
Step 4: Listen for webhooks
11
Each individual transfer triggers its own webhook (payout.completed or payout.failed). Use the transactionId from the bulk payout response to correlate webhook events with specific orders.

​
Key behaviors

BehaviorDescription
Independent processingEach transfer is validated and processed separately. A single failure does not block other orders.
Balance pre-checkThe system validates that your wallet balance covers the total amount plus all fees before processing any orders.
Individual transaction recordsEvery order generates its own transactionId and transaction record for full traceability.
Quote expiryBulk quotes expire after 10 minutes. Submit your payout promptly after quoting.
Rate limitsThe bulk endpoint enforces payload size limits. Contact support for your account’s maximum orders per request.
Audit trailBoth 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 Quote API

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

Fetch Bulk Quotes API

Retrieve existing quotes via GET /v1/bulk/quote.

Create Bulk Payout API

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

Single Payout Guide

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