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.monerail.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": "237670000777", "operator": "MTN" },
    "client_reference": "inv_118"
  }'

Bank transfer

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": 150000,
  "currency": "XAF",
  "recipient": { "type": "bank", "name": "Kossi Mensah", "bank_code": "10005", "account": "10005000100123456784821" }
}

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

Money and statuses

When you create a payout, Monerail 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. It is the only protection against paying twice after a network error.
  • 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.