Skip to main content
The Collections API enables you to accept payments (collect money) from customers via mobile money.

​
Overview

Use collections to:
  • Accept payments for goods and services
  • Process subscription payments
  • Collect bills and invoices
  • Accept 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

View the interactive API reference for Collections endpoints