Digital Wallet

AfriRoute uses a pre-funded wallet to settle payouts, billing, and platform fees. Track balances in real time, top up, and reconcile every movement through the ledger.

Overview

Your wallet is the funding source for outbound money movement (payouts, refunds, disbursements) and the account that platform fees are deducted from. Each wallet supports multiple currencies, low-balance alerts, and optional auto-recharge.

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

Endpoints

Get Balance

GET /v1/wallet/balance

curl https://api.afriroute.ai/api/v1/wallet/balance \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY"

{
  "balance": 15000.00,
  "currency": "ETB",
  "available": 14200.00,
  "pending": 800.00,
  "low_balance_alert": 5000.00,
  "last_topup": "2026-05-01T10:00:00Z"
}

Top Up

POST /v1/wallet/topup

Field	Type	Required	Description
amount	number	Yes	Amount to add
currency	string	Yes	ISO 4217 code
payment_method	string	Yes	bank_transfer, mobile_money, card
reference	string	No	Your reconciliation reference

const res = await fetch('https://api.afriroute.ai/api/v1/wallet/topup', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer $AFRIROUTE_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({
    amount: 10000,
    currency: 'ETB',
    payment_method: 'bank_transfer',
    reference: 'TXN_BANK_123'
  })
});
console.log(await res.json());

import requests

requests.post(
    'https://api.afriroute.ai/api/v1/wallet/topup',
    headers={'Authorization': 'Bearer $AFRIROUTE_API_KEY'},
    json={'amount': 50000, 'currency': 'KES', 'payment_method': 'mobile_money'}
)

Transaction Ledger

GET /v1/wallet/transactions

Param	Type	Description
start_date	string	Inclusive ISO date
end_date	string	Inclusive ISO date
type	string	topup, payout, fee, refund
limit	integer	Page size, default 50

curl "https://api.afriroute.ai/api/v1/wallet/transactions?type=payout&limit=20" \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY"

{
  "total": 234,
  "transactions": [
    {
      "transaction_id": "txn_001",
      "type": "payout",
      "amount": -1000.00,
      "balance_after": 14000.00,
      "currency": "ETB",
      "created_at": "2026-05-28T09:35:00Z"
    }
  ]
}

Configure Auto-Recharge

POST /v1/wallet/auto-recharge

curl -X POST https://api.afriroute.ai/api/v1/wallet/auto-recharge \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": true, "threshold": 5000, "recharge_amount": 20000, "currency": "ETB" }'

Best Practices

• Enable low-balance alerts and auto-recharge so payouts never fail mid-batch.
• Reconcile your books against the wallet ledger daily using balance_after.
• Keep at least one full payout cycle of funds available to absorb timing gaps.
• Use distinct reference values on top-ups to match bank deposits to wallet credits.

Error Handling

Code	Description	Action
INSUFFICIENT_WALLET_BALANCE	Not enough funds	Top up the wallet
TOPUP_PENDING	Top-up not yet cleared	Wait for confirmation
CURRENCY_MISMATCH	Operation currency differs from wallet	Use a matching currency

Related Links

• Payouts
• Billing
• Invoicing
• Payments API Reference

---

Last Updated: May 2026