Payouts & Disbursements

Send money to mobile wallets in bulk or one at a time — for gig-worker payments, merchant settlements, refunds, and supplier payouts across Africa.

Overview

A payout debits your AfriRoute wallet and credits a recipient's mobile money account via Telebirr, M-Pesa, MTN MoMo, or Airtel Money. Single payouts settle in seconds to minutes; bulk payouts process a batch and report per-item status.

Base URL: https://api.afriroute.ai — Auth: Authorization: Bearer $AFRIROUTE_API_KEY

Endpoints

Send a Payout

POST /v1/payments/payout

Field	Type	Required	Description
amount	number	Yes	Amount in major units
currency	string	Yes	ISO 4217 code
phone_number	string	Yes	Recipient (E.164)
provider	string	Yes	telebirr, mpesa, mtn_momo, airtel_money
reason	string	No	Human-readable purpose
reference	string	Yes	Your unique idempotency key
metadata	object	No	Reference data

curl -X POST https://api.afriroute.ai/api/v1/payments/payout \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 1000,
    "currency": "ETB",
    "phone_number": "+251911234567",
    "provider": "telebirr",
    "reason": "Delivery payment #45678",
    "reference": "PAYOUT_45678"
  }'

{
  "payout_id": "out_xyz789",
  "status": "processing",
  "amount": 1000,
  "currency": "ETB",
  "recipient": "+251911234567",
  "estimated_arrival": "2026-05-28T09:35:00Z"
}

Bulk Payouts

POST /v1/payments/payout/bulk

const res = await fetch('https://api.afriroute.ai/api/v1/payments/payout/bulk', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer $AFRIROUTE_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    description: 'Weekly driver payouts',
    payouts: [
      { amount: 500, currency: 'ETB', phone_number: '+251911111111', provider: 'telebirr', reference: 'DRV_001' },
      { amount: 750, currency: 'ETB', phone_number: '+251922222222', provider: 'telebirr', reference: 'DRV_002' }
    ]
  })
});
console.log(await res.json());

import requests

requests.post(
    'https://api.afriroute.ai/api/v1/payments/payout/bulk',
    headers={'Authorization': 'Bearer $AFRIROUTE_API_KEY'},
    json={
        'description': 'Supplier settlement',
        'payouts': [
            {'amount': 2000, 'currency': 'KES', 'phone_number': '+254712345678',
             'provider': 'mpesa', 'reference': 'SUP_900'}
        ]
    }
)

{
  "batch_id": "batch_abc123",
  "total_payouts": 2,
  "total_amount": 1250,
  "currency": "ETB",
  "status": "processing",
  "payouts": [
    { "payout_id": "out_001", "status": "pending" },
    { "payout_id": "out_002", "status": "pending" }
  ]
}

Get Payout Status

GET /v1/payments/payout/:payout_id

curl https://api.afriroute.ai/api/v1/payments/payout/out_xyz789 \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY"

Statuses: pending, processing, completed, failed, reversed.

Use Cases

• Gig-worker and driver payments
• Merchant and marketplace settlements
• Customer refunds
• Salaries, commissions, and supplier payments

Best Practices

• Always pass a unique reference per payout to make retries idempotent and avoid double-paying.
• Confirm your wallet balance covers the batch before submitting; insufficient funds reject the whole batch.
• Reconcile against the per-item statuses in webhooks rather than assuming batch success.
• Validate recipient numbers to E.164 before sending to cut INVALID_RECIPIENT failures.

Error Handling

Code	Description	Action
INSUFFICIENT_WALLET_BALANCE	Wallet too low	Top up the wallet
DUPLICATE_REFERENCE	Reference already used	Use a new reference
INVALID_RECIPIENT	Bad phone number	Validate to E.164
PAYOUT_LIMIT_EXCEEDED	Above per-txn limit	Split the amount

Related Links

• Wallet
• Mobile Money
• Fraud Prevention
• Payments API Reference

---

Last Updated: May 2026