Docs
ENFR
Dashboard
Products

Payouts

Send money to mobile money wallets and bank accounts.

A payout sends money from your balance to someone else: a supplier, an employee, a customer. Mobile money and bank transfers use the same endpoint, in every currency of Amounts and currencies, NGN included.

Mobile money

bash
curl https://api.monerails.com/v1/payouts \
  -H "Authorization: Bearer $MONERAIL_KEY" \
  -H "Idempotency-Key: payout-inv-118" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150000,
    "currency": "XAF",
    "recipient": { "type": "mobile_money", "name": "Kossi Mensah", "phone": "237660000001", "operator": "MTN" },
    "client_reference": "inv_118"
  }'

Bank transfer

Activation in progress. Bank payouts open with the markets being activated (Ghana, Kenya, Nigeria, Rwanda, Tanzania and Uganda). Until then, a bank payout returns 400 bank_transfer_unsupported in every country, and the example below is illustrative.

Find the bank with List banks and send its code exactly as returned. A bank name or a code that does not match exactly fails with 400 bank_account_invalid.

JSON
{
  "amount": 5000000,
  "currency": "NGN",
  "recipient": { "type": "bank", "name": "Chidi Okafor", "country": "NG", "bank_code": "044", "account": "0123454821" }
}

Account numbers are masked in every response (••••4821).

Money and statuses

When you create a payout, Monerails reserves amount + fee on your balance. If it does not cover both, the request fails with 402 balance_insufficient and nothing is sent.

Status Meaning
pending, processing On its way. The money is reserved.
succeeded Received by the recipient.
failed Not delivered. amount + fee returns to your balance, and payout.failed is sent.

The reservation shows in transactions as a payout with status pending, then succeeded, or failed with a payout_reversal that gives the money back.

Safety

  • Always send an Idempotency-Key and a unique client_reference. The key protects your retries for 24 hours; the reference lets you find the payout afterwards.
  • Payouts need a key created by an Owner, Finance or Approver member.
  • A 202 response means the payment partner has not confirmed receipt yet. Do not create the payout again: wait for the webhook, or retrieve it.