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.

​
Initiate a Collection

POST /api/v1/bila/collections/mobile-money
ParameterTypeRequiredDescription
amountnumberYesMinimum 0.01
referencestringYesUnique — pattern ^[a-zA-Z0-9._-]+$
phonestringYesCustomer’s mobile money number
operatorstringYesmtn, airtel, or zamtel
countrystringYeszm
walletIdstringYesYour sandbox wallet ID (UUID)
bearerstringNomerchant (default) or customer
narrationstringNoMax 100 characters
customerNamestringNoMax 100 characters
Example: 
curl --request POST \
  --url https://sandbox.usebila.com/api/v1/bila/collections/mobile-money \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: sk_test_your_api_key_here' \
  --data '{
    "amount": 150.00,
    "reference": "INV-2026-001",
    "phone": "0966123456",
    "operator": "mtn",
    "country": "zm",
    "walletId": "68f11209-451f-4a15-bfcd-d916eb8b09f4",
    "narration": "Payment for April invoice",
    "customerName": "John Banda"
  }'
Response: 
{
  "status": true,
  "message": "Operation completed successfully",
  "data": {
    "id": "col-uuid",
    "reference": "INV-2026-001",
    "status": "successful",
    "amount": 150.00,
    "currency": "ZMW",
    "customer": {
      "phone": "0966123456",
      "name": "John Banda",
      "operator": "mtn"
    },
    "createdAt": "2026-05-05T10:30:00Z"
  }
}

​
Check Collection Status

curl --request GET \
  --url https://sandbox.usebila.com/api/v1/bila/collections/status/INV-2026-001 \
  --header 'x-api-key: sk_test_your_api_key_here'
StatusMeaning
pendingAwaiting final outcome
successfulFunds credited to wallet
failedTransaction failed

​
Pre-Launch Checklist

  • Successful collection returns "status": "successful"
  • Reference with fail returns "status": "failed"
  • Duplicate reference returns 409
  • Status polling transitions correctly from pending