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.
Overview
The Bila Sandbox mirrors the production API exactly — same endpoints, same authentication, same response shapes — but all transactions are fully simulated. No real money moves, no SMS or emails are sent.
Sandbox and production are completely isolated. Sandbox keys, wallet IDs, and data do not carry over to production.
What the Sandbox Simulates
| Feature | Behaviour |
|---|
| Collections and transfers | Fully simulated — no real money moves |
| Wallet balance | Not fixed — it changes accordingly (simulated) |
| SMS and email notifications | Not sent — use the status endpoint instead |
| Webhook delivery | Works — events fire to your registered URL |
| OTP (if required) | Default is 000000 |
Setup
1. Activate the Sandbox
- Log in to your Bila Merchant Dashboard
- Go to Settings → API Keys and Click Activate Sandbox
- Click Create API Key
- Copy and save your key — it will not be shown again in full
Your sandbox secret key is prefixed with sk_test_.
Store your API key in an environment variable. Never commit it to source control or log it.
2. Verify Your Connection
curl --request GET \
--url https://sandbox.usebila.com/api/v1/bila/accounts \
--header 'x-api-key: sk_test_your_api_key_here'
{
"status": true,
"message": "Operation completed successfully",
"data": {
"data": [
{
"id": "68f11209-451f-4a15-bfcd-d916eb8b09f4",
"type": "main",
"status": "active",
"currency": "ZMW",
"createdAt": "2024-01-15T10:30:00Z",
"details": {
"type": "bank-account",
"accountName": "John Doe",
"tillNumber": "123456"
},
"availableBalance": "1500.00",
"ledgerBalance": "1500.00"
}
],
"meta": {
"total": 1,
"perPage": 50,
"currentPage": 1,
"pageCount": 1
}
}
}
walletId — you will need it for collections and transfers.
Base URLs
| Environment | URL |
|---|
| Sandbox | https://sandbox.usebila.com/api/v1 |
| Production | https://api.usebila.com/api/v1 |
Authentication
Include your secret key in every request:
x-api-key: sk_test_your_api_key_here
x-api-key in lowercase. No Bearer tokens are used on merchant-facing routes.
| Key Type | Prefix | Header |
|---|
| Secret Key | sk_test_ | x-api-key |
| Publishable Key | pk_test_ | x-publishable-key |
Test Data
Supported Providers
| Provider | operator value | Example Number |
|---|
| MTN Mobile Money | mtn | 096XXXXXXX |
| Airtel Money | airtel | 097XXXXXXX |
| Zamtel Kwacha | zamtel | 095XXXXXXX |
Simulating Success and Failure
By default all transactions succeed. To trigger a failure, include the substring fail anywhere in your reference:
INV-2026-fail-001 ✓ fails
test-payment-will-fail ✓ fails
INV-2026-001 ✓ succeeds
The sandbox does not expose specific PSP error codes. Outcomes are binary — successful or failed — with a message string stating the reason.
Limitations
| Limitation | Detail |
|---|
| One wallet only | Sandbox has a single Main Wallet — sub-wallets require production |
| No PSP error codes | Failures are binary — successful or failed only |
| No SMS or email | Notifications suppressed — use status endpoint or webhooks |
| Wallet balance | Not fixed — it changes accordingly (simulated) |
Support
