> ## Documentation Index
> Fetch the complete documentation index at: https://developers.kulmipay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Sandbox

> Test your KulmiPay integration in sandbox before switching to live payments.

Use the KulmiPay sandbox to build and test your integration without moving real money. Sandbox and live are separate environments with separate accounts, credentials, API URLs, and checkout URLs.

<Warning>
  Never mix sandbox and live credentials. Sandbox keys only work on `sandbox.kulmipay.com`, and live keys only work on `app.kulmipay.com`.
</Warning>

## Integration testing environment

KulmiPay provides two environments:

* **Sandbox / development** for testing integrations.
* **Live / production** for real transactions.

All API requests should be made over HTTPS. Webhook callback URLs should also use HTTPS and be publicly reachable.

## Resources for KulmiPay integration and API testing

### Sandbox / development environment

Use sandbox while building and testing your application.

| Resource          | URL                                             |
| ----------------- | ----------------------------------------------- |
| Sandbox dashboard | `https://sandbox.kulmipay.com`                  |
| API base URL      | `https://sandbox.kulmipay.com/api/`             |
| API v1 base URL   | `https://sandbox.kulmipay.com/api/v1/`          |
| Checkout API      | `https://sandbox.kulmipay.com/api/v1/checkout/` |
| Checkout page     | `https://checkout-sandbox.kulmipay.com`         |

Sandbox API keys use test prefixes:

| Key        | Prefix              |
| ---------- | ------------------- |
| Public key | `ISPubKey_test_`    |
| Secret key | `ISSecretKey_test_` |

Create sandbox keys from **API Applications** in the sandbox dashboard.

### Live environment

Use live only when you are ready to process real payments.

| Resource        | URL                                         |
| --------------- | ------------------------------------------- |
| Live dashboard  | `https://app.kulmipay.com`                  |
| Sign up         | `https://app.kulmipay.com/account/signup/`  |
| API base URL    | `https://app.kulmipay.com/api/`             |
| API v1 base URL | `https://app.kulmipay.com/api/v1/`          |
| Checkout API    | `https://app.kulmipay.com/api/v1/checkout/` |
| Checkout page   | `https://checkout.kulmipay.com`             |

Live API keys use live prefixes:

| Key        | Prefix              |
| ---------- | ------------------- |
| Public key | `ISPubKey_live_`    |
| Secret key | `ISSecretKey_live_` |

## Testing details for sandbox environment

### Create a checkout session

Use your sandbox public key to create a test checkout.

```bash theme={null}
curl -X POST https://sandbox.kulmipay.com/api/v1/checkout/ \
  -H "Content-Type: application/json" \
  -d '{
    "public_key": "ISPubKey_test_xxxxxxxxxxxxxxxx",
    "amount": 1000,
    "currency": "KES",
    "email": "customer@example.com",
    "phone_number": "254723890353",
    "api_ref": "ORDER-1001",
    "redirect_url": "https://merchant.example/thank-you"
  }'
```

### Authenticate protected sandbox requests

For backend-only API calls, pass your sandbox secret key as a Bearer token.

```bash theme={null}
curl --request GET \
  --url https://sandbox.kulmipay.com/api/v1/wallets/ \
  --header 'Authorization: Bearer ISSecretKey_test_xxxxxxxxxxxxxxxx'
```

### Test M-Pesa phone numbers

| Phone number   | Simulated behavior |
| -------------- | ------------------ |
| `254723890353` | Payment succeeds   |
| `254700000000` | Payment fails      |
| `254711111111` | Payment times out  |

### Test amounts

Use small amounts such as `1`, `5`, or `10` to keep test records easy to review.

## Switching from sandbox to live

When you are ready to go live:

1. Replace `https://sandbox.kulmipay.com` with `https://app.kulmipay.com`.
2. Replace sandbox keys with live keys.
3. Use `https://checkout.kulmipay.com` for live hosted checkout.
4. Point webhooks to your production HTTPS endpoint.
5. Complete live business verification before processing real payments.

<Note>
  If you are using the `kulmipay` browser SDK, set `live: true` when switching to production.
</Note>