Send Payouts
Move money from an Aella Wallet to Nigerian bank accounts with validation, fee checks, status queries, and transfer webhooks.
Use this flow when your platform needs to pay vendors, drivers, creators, sellers, staff, or customers after a balance becomes payable.
1. Check bank availability
Call GET /transfers/bank/health before sending time-sensitive payouts. Use it to avoid routing through banks that are temporarily degraded.
curl https://api.aellaapp.com/transfers/bank/health \
-H "Authorization: Bearer {token}"
2. Resolve the recipient account
Fetch supported banks with GET /transfers/banks, then call GET /transfers/name-enquiry with the recipient bankCode and accountNumber.
Only continue when the returned account name matches the recipient you expect.
3. Estimate the fee
Call GET /transfers/fee with the payout amount. Show the fee before submitting the transfer when your user is funding the payout or when your ledger needs the exact debit amount.
4. Send the payout
Use POST /transfers for one recipient and POST /transfers/bulk for many recipients. Provide a unique reference or externalReference so retries and reconciliation can identify the payout.
curl https://api.aellaapp.com/transfers \
-X POST \
-H "Authorization: Bearer {token}" \
-H "Content-Type: application/json" \
-d '{"accountNumber":"0123456789","bankCode":"000014","amount":5000,"currency":"NGN","narration":"Vendor payout","reference":"merchant-payout-ref-001"}'
5. Reconcile final status
Prefer webhooks: transfer.completed and transfer.failed. Your webhook handler should be idempotent because deliveries can retry.
If you need to poll, use GET /transfers/verify with your merchant reference, or GET /transfers/{id} when you have the transfer id.