Skip to main content
POST
/
v1
/
bulk
/
payout
Create Bulk Payout
const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    items: [
      {
        referenceNumber: '12345',
        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: '67890',
        targetAmount: '1100',
        reason: 'Salary payment',
        recipient: {
          name: 'NNOROM UZOMA CHUKWUDI',
          account: {bankName: 'FCMB', sortCode: '214', accountNumber: '2483520014'},
          paymentChannel: 'BANK_TRANSFER',
          currency: 'NGN',
          country: 'NG'
        }
      }
    ],
    source: {currency: 'NGN', country: 'NG'},
    target: {currency: 'NGN', country: 'NG'},
    paymentChannel: 'BANK_TRANSFER',
    remark: 'June 2026 Salary'
  })
};

fetch('https://sandboxapi.me-cash.com/v1/bulk/payout', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));
{
  "message": "bulk order processed",
  "status": "success",
  "data": {
    "bulkReference": "00a5478d-272a-4be0-8c77-d85be1ec5ea8",
    "status": "SUCCESS",
    "totalRequested": 2,
    "successfulCount": 2,
    "failedCount": 0,
    "totalAmount": 350.5,
    "totalFees": 400,
    "orders": [
      {
        "id": "77250b66-9bb7-4d5a-a634-0b16659959fe",
        "remark": "payment 1",
        "reason": "Gift",
        "referenceNumber": "IE8YGOSWDG9HN",
        "type": "SEND",
        "state": "PENDING",
        "quote": {
          "id": "4be1d423-e2eb-437d-8223-16cfcb308195",
          "paymentChannel": "BANK_TRANSFER",
          "source": {
            "currency": "NGN",
            "country": "NG",
            "amount": 250.5
          },
          "target": {
            "currency": "NGN",
            "country": "NG",
            "amount": 250.5
          },
          "rate": 1,
          "fee": {
            "amount": 200,
            "stampDuty": 0
          },
          "summary": {
            "total": 450.5
          },
          "settlement": "30 Mins",
          "quoteCurrency": "NGN"
        },
        "recipient": {
          "name": "NNOROM UZOMA CHUKWUDI",
          "account": {
            "bankName": "FCMB",
            "sortCode": "214",
            "accountNumber": "2483520014"
          },
          "paymentChannel": "BANK_TRANSFER",
          "currency": "NGN",
          "country": "NG"
        },
        "created": "2026-03-25T10:50:06.115252622Z",
        "processed": "2026-03-25T10:50:06.115252622Z",
        "bulkReference": "00a5478d-272a-4be0-8c77-d85be1ec5ea8"
      },
      {
        "id": "17f755c3-f7fc-4ab5-b076-c3f3eb912155",
        "remark": "payment 2",
        "reason": "Gift",
        "referenceNumber": "AXZYRRN5PBDIO",
        "type": "SEND",
        "state": "PENDING",
        "quote": {
          "id": "cf132126-af1c-4fd7-b924-427826a34b64",
          "paymentChannel": "BANK_TRANSFER",
          "source": {
            "currency": "NGN",
            "country": "NG",
            "amount": 100
          },
          "target": {
            "currency": "NGN",
            "country": "NG",
            "amount": 100
          },
          "rate": 1,
          "fee": {
            "amount": 200,
            "stampDuty": 0
          },
          "summary": {
            "total": 300
          },
          "settlement": "30 Mins",
          "quoteCurrency": "NGN"
        },
        "recipient": {
          "name": "NNOROM UZOMA CHUKWUDI",
          "account": {
            "bankName": "FCMB",
            "sortCode": "214",
            "accountNumber": "2483520014"
          },
          "paymentChannel": "BANK_TRANSFER",
          "currency": "NGN",
          "country": "NG"
        },
        "created": "2026-03-25T10:50:07.309355914Z",
        "processed": "2026-03-25T10:50:07.309355914Z",
        "bulkReference": "00a5478d-272a-4be0-8c77-d85be1ec5ea8"
      }
    ],
    "createdAt": "2026-03-25T10:50:07.810009313Z"
  }
}
This API is still under construction.

​
Error responses

StatusMessageWhat it meansHow to fix
400Insufficient wallet balance for transactionWallet balance cannot cover the total payout amount plus fees.Top up the wallet or reduce the number of orders before retrying.
400Quotes only last for 10 minutesOne or more referenced quotes expired before submission.Generate fresh bulk quotes and submit the payout immediately.
400Invalid country or currency ISO codeUnsupported country/currency combination in a recipient.Use corridor-supported ISO codes for both quote and recipient data.
400Account name mismatch, use account enquiry endpointAccount name in payload differs from bank enquiry results.Re-run account enquiry and match the returned account name.
400Invalid Bank SortcodeSort code missing, malformed, or unsupported.Fetch the correct sort code from the bank list and verify formatting.
400{field_name} cannot be emptyRequired recipient field omitted from the payload.Fill in every mandatory field (name, account number, etc.) before submitting.
400Duplicate quote ID in bulk orderThe same quote ID was provided multiple times in the bulk order request.Ensure each quote ID is unique within the same bulk order.
401API key missing or incorrectx-api-key header absent, invalid, or expired.Supply the correct API key for the environment you are targeting.
403IP not whitelistedRequest originated from an unapproved IP.Add your server IP to the dashboard allowlist.
422Invalid quote ID providedQuote ID missing, invalid, expired, or already consumed.Create new bulk quotes and reference them in the payout call.
500Service temporarily unavailableTemporary backend/service disruption.Retry with exponential backoff; contact support if it persists.

Authorizations

​
x-api-key
string
header
required

Body

application/json
​
items
object[]
required

List of payout orders to process in the bulk payload.

​
source
object
required

The source currency and country for the batch.

​
target
object
required

The target currency and country for the batch.

​
paymentChannel
enum<string>
required

The overall payment channel intended for the batch.

Available options:
BANK_TRANSFER,
MOBILE_MONEY
Example:

"BANK_TRANSFER"

​
remark
string
required

A general remark for the bulk payout.

Example:

"June 2026 Salary"

Response

Bulk payout submitted successfully.

​
message
string
Example:

"bulk payout queued"

​
status
string
Example:

"success"

​
data
object