Payments API Reference

Complete reference for the AfriRoute Payments APIs: mobile money, payouts, wallet, billing, invoicing, and fraud prevention.

Overview

• Base URL: https://api.afriroute.ai
• Auth: Authorization: Bearer $AFRIROUTE_API_KEY
• Content type: application/json
• Rate limit: 100 requests/second per key
• Currencies: ETB, KES, TZS, UGX, GHS, RWF, ZMW, NGN, and more

Mobile Money

Method	Path	Description
POST	/v1/payments/mobile/initiate	Start a mobile money charge
GET	/v1/payments/mobile/:payment_id	Get payment status

curl -X POST https://api.afriroute.ai/api/v1/payments/mobile/initiate \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "amount": 500, "currency": "ETB", "phone_number": "+251911234567", "provider": "telebirr" }'

const res = await fetch('https://api.afriroute.ai/api/v1/payments/mobile/initiate', {
  method: 'POST',
  headers: { 'Authorization': 'Bearer $AFRIROUTE_API_KEY', 'Content-Type': 'application/json' },
  body: JSON.stringify({ amount: 1000, currency: 'KES', phone_number: '+254712345678', provider: 'mpesa' })
});
console.log((await res.json()).payment_id);

import requests

requests.post(
    'https://api.afriroute.ai/api/v1/payments/mobile/initiate',
    headers={'Authorization': 'Bearer $AFRIROUTE_API_KEY'},
    json={'amount': 50, 'currency': 'GHS', 'phone_number': '+233241234567', 'provider': 'mtn_momo'}
)

Payouts

Method	Path	Description
POST	/v1/payments/payout	Send a single payout
POST	/v1/payments/payout/bulk	Send a batch of payouts
GET	/v1/payments/payout/:payout_id	Get payout status

{
  "payout_id": "out_xyz789",
  "status": "processing",
  "amount": 1000,
  "currency": "ETB",
  "recipient": "+251911234567"
}

Wallet

Method	Path	Description
GET	/v1/wallet/balance	Current balance
POST	/v1/wallet/topup	Add funds
GET	/v1/wallet/transactions	Ledger history
POST	/v1/wallet/auto-recharge	Configure auto-recharge

Billing & Subscriptions

Method	Path	Description
POST	/v1/billing/plans	Create a plan
POST	/v1/billing/subscriptions	Subscribe a customer
DELETE	/v1/billing/subscriptions/:id	Cancel a subscription

Invoicing

Method	Path	Description
POST	/v1/billing/invoices	Create an invoice
POST	/v1/billing/invoices/:id/send	Send/resend
GET	/v1/billing/invoices/:id	Get an invoice
POST	/v1/billing/invoices/:id/void	Void an invoice

Fraud Prevention

Method	Path	Description
POST	/v1/payments/risk-check	Score a transaction
POST	/v1/payments/fraud/rules	Create a rule
POST	/v1/payments/fraud/blacklist	Add to blacklist

Transactions

GET /v1/payments/transactions

Param	Type	Description
start_date	string	Inclusive ISO date
end_date	string	Inclusive ISO date
status	string	completed, failed, etc.
limit	integer	Page size, default 50

Webhooks

AfriRoute posts events to your callback_url. Verify the X-AfriRoute-Signature HMAC-SHA256 header against your webhook secret.

Event	Description
payment.completed	Mobile money charge succeeded
payment.failed	Charge declined/failed
payout.completed	Payout delivered
invoice.payment_succeeded	Invoice paid
subscription.cancelled	Subscription ended

const crypto = require('crypto');

function verify(payload, signature, secret) {
  const hash = crypto.createHmac('sha256', secret)
    .update(JSON.stringify(payload)).digest('hex');
  return hash === signature;
}

Payment Statuses

pending · processing · completed · failed · cancelled · expired

Error Codes

Code	HTTP	Description
UNAUTHORIZED	401	Missing/invalid API key
INSUFFICIENT_FUNDS	402	Customer wallet too low
INSUFFICIENT_WALLET_BALANCE	402	Your wallet too low for payout
INVALID_PHONE	422	Bad phone number format
PROVIDER_UNAVAILABLE	503	Provider outage
RATE_LIMITED	429	Exceeded 100 req/s
DUPLICATE_REFERENCE	409	Idempotency key reused

Related Links

• Mobile Money
• Payouts
• Wallet
• Fraud Prevention

---

Last Updated: May 2026