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({
    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'
      }
    ]
  })
};

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 payout queued",
  "status": "success",
  "data": {
    "bulkReference": "BULK-20260324-001",
    "totalOrders": 2,
    "successCount": 2,
    "failedCount": 0,
    "orders": [
      {
        "quoteId": "b70f6798-ae5c-41fd-92c9-d6cfc325b8dc",
        "transactionId": "f4e597cc-18fa-4c23-b9c1-xxxxxxxxxxxxx",
        "status": "PROCESSING",
        "recipientName": "NNOROM UZOMA CHUKWUDI",
        "message": "payout queued"
      },
      {
        "quoteId": "faeafe20-d5c8-47b5-913a-2c81d15a69cb",
        "transactionId": "a8b2c3d4-5e6f-7890-abcd-xxxxxxxxxxxxx",
        "status": "PROCESSING",
        "recipientName": "NNOROM UZOMA CHUKWUDI",
        "message": "payout queued"
      }
    ]
  }
}

​
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.
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
​
orders
object[]
required

List of payout orders. Each order references a quote and includes recipient details.

Response

Bulk payout submitted successfully.

​
message
string
Example:

"bulk payout queued"

​
status
string
Example:

"success"

​
data
object