> ## 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.

# Sandbox Overview

> Test your Bila integration safely before going live — no real money, no real consequences.

## 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.

<Info>
  Sandbox and production are completely isolated. Sandbox keys, wallet IDs, and data do not carry over to production.
</Info>

***

## 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

1. Log in to your Bila Merchant Dashboard
2. Go to **Settings → API Keys** and Click **Activate Sandbox**
3. Click **Create API Key**
4. Copy and save your key — it will not be shown again in full

Your sandbox secret key is prefixed with `sk_test_`.

<Warning>
  Store your API key in an environment variable. Never commit it to source control or log it.
</Warning>

### 2. Verify Your Connection

```bash theme={null}
curl --request GET \
  --url https://sandbox.usebila.com/api/v1/bila/accounts \
  --header 'x-api-key: sk_test_your_api_key_here'
```

**Expected response:**

```json theme={null}
{
  "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:

```bash theme={null}
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`:

```text theme={null}
INV-2026-fail-001       ✓ fails
test-payment-will-fail  ✓ fails
INV-2026-001            ✓ succeeds
```

<Info>
  The sandbox does not expose specific PSP error codes. Outcomes are binary — `successful` or `failed` — with a message string stating the reason.
</Info>

***

## 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](mailto:support@usebila.com) — include your transaction `reference` or `X-Bila-Delivery` ID