---
title: Sandbox Testing
description: Test your integration safely before going live
---

The sandbox environment lets you test your integration without making real purchases or affecting production data.

## Sandbox vs Production

| Aspect            | Sandbox                    | Production         |
| ----------------- | -------------------------- | ------------------ |
| Base URL          | `/api/partners/sandbox/v1` | `/api/partners/v1` |
| API Key Prefix    | `sk_test_`                 | `sk_live_`         |
| Real Transactions | No                         | Yes                |
| Real Charges      | No                         | Yes                |
| Webhooks          | Test payloads              | Real events        |
| Rate Limits       | 60/min (all tiers)         | Tier-based         |
| Max Webhooks      | 1                          | 3                  |

## Getting Sandbox Credentials

1. Go to [Settings > API Keys](https://my.rizpay.app/settings/api)
2. Click **Create New Key**
3. Select **Sandbox** environment
4. Copy your `sk_test_` key

## Making Sandbox Requests

Use the sandbox base URL with your test key:

```bash
curl -X GET \
  -H "Authorization: Bearer sk_test_your_test_key" \
  https://my.rizpay.app/api/partners/sandbox/v1/account/balance
```

## Sandbox Behavior

### Account Balance

Returns a mock balance for testing:

```json
{
  "status": { "code": 200, "message": "Success" },
  "data": {
    "balance": "100000.00",
    "currency": "NGN",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}
```

### Products

Returns real product data. Use these products in your test purchases.

### Purchases

Creates mock transactions:

1. **Initial status**: `pending`
2. **After query**: Transitions to `successful`

No real airtime or data is delivered. No balance is deducted.

```bash
# Create a test purchase
curl -X POST \
  -H "Authorization: Bearer sk_test_your_test_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prd_42",
    "phone_number": "08012345678",
    "amount": "100.00",
    "external_reference": "1736234400T3S4T5"
  }' \
  https://my.rizpay.app/api/partners/sandbox/v1/purchases
```

### Transaction Status

Query a transaction to simulate completion:

```bash
# Query to complete the transaction
curl -X POST \
  -H "Authorization: Bearer sk_test_your_test_key" \
  https://my.rizpay.app/api/partners/sandbox/v1/purchases/txn_abc123/query
```

The transaction will immediately become `successful`.

### Webhooks

Sandbox webhooks fire with test payloads. Use them to:

- Test your webhook endpoint
- Verify signature validation
- Debug payload handling

## Test Phone Numbers

Use any valid Nigerian phone number format:

- `08012345678`
- `08112345678`
- `07012345678`
- `09012345678`

## Test Meter/Decoder Numbers

For electricity and cable TV testing, use these formats:

- Meter numbers: Any 11-13 digit number
- Decoder numbers: Any 10-11 digit number

## Environment Isolation

Sandbox and production are completely isolated:

| Aspect       | Behavior                                        |
| ------------ | ----------------------------------------------- |
| API Keys     | Sandbox keys only work on sandbox endpoints     |
| Transactions | Sandbox transactions don't appear in production |
| Webhooks     | Configured separately for each environment      |
| Data         | No data sharing between environments            |

Attempting to use a sandbox key on production (or vice versa) returns:

```json
{
  "status": {
    "code": 403,
    "message": "Forbidden"
  },
  "error": {
    "code": "ENVIRONMENT_MISMATCH",
    "message": "Sandbox API keys can only access sandbox endpoints"
  }
}
```

## Testing Checklist

Before going live, verify:

- [ ] **Authentication** - API key works correctly
- [ ] **Products** - Can list and filter products
- [ ] **Purchases** - Can create purchases
- [ ] **Status Checks** - Can query transaction status
- [ ] **Verification** - Meter/decoder verification works (electricity/cable)
- [ ] **Error Handling** - Handles all error codes gracefully
- [ ] **Webhooks** - Receives and verifies webhook payloads
- [ ] **Rate Limits** - Handles 429 responses correctly
- [ ] **Duplicate Prevention** - External reference prevents duplicates

## Going Live

When you're ready for production:

1. Create a production API key (`sk_live_`)
2. Update your base URL to `/api/partners/v1`
3. Configure production webhooks
4. Test with small amounts first
5. Monitor your first few transactions

## Next Steps

- [Quick Start](/docs/getting-started/quickstart) - Make your first API call
- [Webhooks](/docs/webhooks/overview) - Set up webhook testing