Sandbox Overview

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'

Expected response:

{
  "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
    }
  }
}

Save your 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

The header name must be exactly 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

Email - support@usebila.com - include your transaction reference or X-Bila-Delivery ID

Integration

Reference

Overview

What the Sandbox Simulates

Setup

1. Activate the Sandbox

2. Verify Your Connection

Base URLs

Authentication

Test Data

Supported Providers

Simulating Success and Failure

Limitations

Support

​Overview

​What the Sandbox Simulates

​Setup

​1. Activate the Sandbox

​2. Verify Your Connection

​Base URLs

​Authentication

​Test Data

​Supported Providers

​Simulating Success and Failure

​Limitations

​Support

Overview

What the Sandbox Simulates

Setup

1. Activate the Sandbox

2. Verify Your Connection

Base URLs

Authentication

Test Data

Supported Providers

Simulating Success and Failure

Limitations

Support