Sandbox Testing

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

Sandbox vs Production

Getting Sandbox Credentials

1. Go to Settings > API Keys
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:

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:

{
  "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 whose outcome is selected by the configured test recipient. A purchase can be immediately successful, pending, failed or reversed. Unrecognized test recipients fail with PURCHASE_FAILED; a valid phone or meter format alone does not select a successful scenario.

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

# Replace prd_42 with an MTN product ID from your own catalogue response.
# Generate and persist a new external_reference for this test order.
curl -X POST \
  -H "Authorization: Bearer sk_test_your_test_key" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "prd_42",
    "network": "MTN",
    "phone_number": "08022222222",
    "amount": "100.00",
    "external_reference": "1736234400T3S4T5"
  }' \
  https://my.rizpay.app/api/partners/sandbox/v1/purchases

Transaction Status

For the pending-success scenario above, query the returned transaction ID to simulate completion:

# Replace the transaction ID with data.id from your purchase response.
curl -X POST \
  -H "Authorization: Bearer sk_test_your_test_key" \
  https://my.rizpay.app/api/partners/sandbox/v1/purchases/txn_abc123/query

This scenario becomes successful. The query endpoint completes any pending sandbox transaction as successful, whichever scenario created it, so leave a pending-failure scenario to its scheduled transition instead of querying it. Query only pending transactions; a completed transaction returns INVALID_STATUS. Read any existing transaction with GET /purchases/:id and inspect data.attributes.status.

Webhooks

Sandbox webhooks fire with test payloads. Use them to:

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

Test Phone Numbers

For airtime and data, use these simulator inputs:

Airtime also supports 08055555555 for VALIDATION_ERROR. Any unrecognized number fails with PURCHASE_FAILED. Pending scenarios transition on their own after about 30 seconds. Wait for that transition when you are testing a pending-then-failed scenario; querying the transaction completes it as successful instead.

Test Meter/Decoder Numbers

Choose the fixture for the scenario you need:

Keep these identifiers as strings and submit the product-specific fields from the electricity or cable TV reference. Verify the meter or decoder before purchasing. These values select simulated outcomes only; do not use them as recipients for production purchases.

Environment Isolation

Sandbox and production are completely isolated:

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

{
  "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 - Make your first API call
• Webhooks - Set up webhook testing