Collections

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

Endpoints

Endpoint	Method	Description
`/bila/collections`	GET	List all collections
`/bila/collections/{id}`	GET	Get a single collection by ID
`/bila/collections/status/{reference}`	GET	Get collection by your reference
`/bila/collections/mobile-money`	POST	Initiate 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

Status	Description
`pending`	Waiting for customer to approve on their phone
`successful`	Payment completed successfully
`failed`	Payment failed or was declined

How It Works

You initiate a collection request
Customer receives a prompt on their phone
Customer enters their PIN to approve
Funds are credited to your wallet
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:

Bearer	Description
`customer`	Fee is added to the amount (customer pays more)
`merchant`	Fee 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 unique references

Use your order ID or invoice number as the reference for easy reconciliation.

Handle pending status

Collections may stay pending while waiting for customer approval. Poll the status or use webhooks.

Show clear descriptions

Use descriptive narrations so customers know what they’re paying for.

⟡

API Reference

Explore the complete API reference

Home

Accounts

Banks

Resolve Account

Transfer Recipients

Transfers

Transactions

Plugins

Collections

Endpoints

Collection Object

Collection Statuses

How It Works

Initiate Collection

Fee Bearer

Check Collection Status

Best Practices

​Endpoints

​Collection Object

​Collection Statuses

​How It Works

​Initiate Collection

​Fee Bearer

​Check Collection Status

​Best Practices

Endpoints

Collection Object

Collection Statuses

How It Works

Initiate Collection

Fee Bearer

Check Collection Status

Best Practices