Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.usebila.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Accept mobile money payments from customers for goods, subscriptions, bills, or donations.

​
Endpoints

EndpointMethodDescription
/bila/collectionsGETList all collections
/bila/collections/{id}GETGet a single collection by ID
/bila/collections/status/{reference}GETGet collection by your reference
/bila/collections/mobile-moneyPOSTInitiate a mobile money collection

​
Collection Object

{
  "id": "col-001",
  "reference": "order-12345",
  "status": "successful",
  "amount": 100.00,
  "currency": "ZMW",
  "narration": "Payment for Order #12345",
  "customer": {
    "phone": "0977123456",
    "name": "JOHN DOE",
    "operator": "airtel"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "completedAt": "2024-01-15T10:31:00Z"
}

​
Collection Statuses

StatusDescription
pendingWaiting for customer to approve on their phone
successfulPayment completed successfully
failedPayment failed or was declined

​
How It Works

  1. You initiate a collection request
  2. Customer receives a prompt on their phone
  3. Customer enters their PIN to approve
  4. Funds are credited to your wallet
  5. You receive a webhook notification (optional)

​
Initiate Collection

curl -X POST "https://api.usebila.com/api/v1/bila/collections/mobile-money" \
  -H "x-api-key: sk_test_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 100,
    "reference": "order-12345",
    "phone": "0977123456",
    "operator": "airtel",
    "country": "zm",
    "walletId": "your-wallet-id",
    "customerName": "John Doe",
    "narration": "Payment for Order #12345"
  }'

​
Fee Bearer

You can specify who pays the transaction fee:
BearerDescription
customerFee is added to the amount (customer pays more)
merchantFee is deducted from the amount (you receive less)
{
  "amount": 100,
  "bearer": "customer",
  // ... other fields
}

​
Check Collection Status

curl -X GET "https://api.usebila.com/api/v1/bila/collections/status/order-12345" \
  -H "x-api-key: sk_test_your_api_key"

​
Best Practices

Use your order ID or invoice number as the reference for easy reconciliation.
Collections may stay pending while waiting for customer approval. Poll the status or use webhooks.
Use descriptive narrations so customers know what they’re paying for.
⟡
API Reference
Explore the complete API reference