Transfers - Bila API Documentation

Initiate a Transfer

POST /api/v1/bila/transfers/mobile-money

Parameter	Type	Required	Description
`amount`	number	Yes	Minimum `0.01`
`reference`	string	Yes	Unique - pattern `^[a-zA-Z0-9._-]+$`
`phone`	string	Yes	Recipient’s mobile money number
`operator`	string	Yes	`mtn`, `airtel`, or `zamtel`
`country`	string	Yes	`zm`
`walletId`	string	No	Defaults to Main Wallet if omitted
`narration`	string	No	Max 100 characters
`recipientName`	string	No	Max 100 characters

Example:

curl --request POST \
  --url https://sandbox.usebila.com/api/v1/bila/transfers/mobile-money \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: sk_test_your_api_key_here' \
  --data '{
    "amount": 250.00,
    "reference": "PAY-2026-001",
    "phone": "0977433571",
    "operator": "airtel",
    "country": "zm",
    "narration": "Supplier payment May",
    "recipientName": "Jane Mwale"
  }'

Response:

{
  "status": true,
  "message": "Operation completed successfully",
  "data": {
    "id": "txn-uuid",
    "reference": "PAY-2026-001",
    "status": "successful",
    "amount": 250.00,
    "currency": "ZMW",
    "recipient": {
      "phone": "0977433571",
      "operator": "airtel"
    },
    "createdAt": "2026-05-05T10:30:00Z"
  }
}

Check Transfer Status

curl --request GET \
  --url https://sandbox.usebila.com/api/v1/bila/transfers/status/PAY-2026-001 \
  --header 'x-api-key: sk_test_your_api_key_here'

Status	Meaning
`pending`	Awaiting final outcome
`successful`	Funds delivered to recipient
`failed`	Transaction failed

Pre-Launch Checklist

Successful transfer returns "status": "successful"
Reference with fail returns "status": "failed"
Amount exceeding balance returns 400 INSUFFICIENT_BALANCE
Status polling transitions correctly from pending