Call any endpoint with your API keys — no Postman required. Open API playground
← Back to Documentation

Sandbox Mode Documentation

Test the MarzPay API without performing real financial transactions or affecting live data.

Overview

Sandbox mode allows developers to test the MarzPay API in a safe testing environment.

How Sandbox Mode Works

Sandbox mode is automatically enabled by default when a business signs up. This allows you to test the API safely without affecting live data.

No additional setup required - sandbox mode is ready to use immediately after registration.

Collect Money API - Sandbox Mode

Endpoint

POST /api/v1/collect-money

Same endpoint as production - Sandbox mode is automatically detected based on business settings

Request Headers

Authorization: Basic YOUR_API_CREDENTIALS
Content-Type: application/json

Request Body

{
    "amount": 5000,
    "phone_number": "+256712345678",
    "reference": "123e4567-e89b-12d3-a456-426614174000",
    "description": "Test collection payment",
    "callback_url": "https://your-webhook-url.com/callback",
    "country": "UG",
    "metadata": [
        { "orderId": "ORD-123456789" },
        { "customerId": "customer@email.com", "isPII": true }
    ]
}

Two different “metadata” concepts: optional request field metadata is your merchant array (echoed as data.collection.metadata on create and as top-level metadata on webhooks). The response object data.metadata below is only response diagnostics (response_timestamp, sandbox_mode) — not merchant data.

Sandbox Response

{
    "status": "success",
    "message": "Collection completed successfully (Sandbox Mode).",
    "data": {
        "transaction": {
            "uuid": "1b28ec9a-5509-44cc-b260-3a84f0c77976",
            "reference": "123e4567-e89b-12d3-a456-426614174000",
            "status": "sandbox",
            "provider_reference": "SANDBOX_MTN_1758370330"
        },
        "collection": {
            "amount": {
                "formatted": "5,000.00",
                "raw": 5000,
                "currency": "UGX"
            },
            "provider": "mtn",
            "phone_number": "+256712345678",
            "mode": "sandbox",
            "metadata": [
                { "orderId": "ORD-123456789" },
                { "customerId": "customer@email.com", "isPII": true }
            ]
        },
        "timeline": {
            "initiated_at": "2025-09-20 15:12:10",
            "estimated_settlement": "N/A (Sandbox Mode)"
        },
        "metadata": {
            "response_timestamp": "2025-09-20 15:12:10",
            "sandbox_mode": true,
            "test_phone_number": false
        }
    }
}

data.collection.metadata = your merchant metadata (if sent). data.metadata = API response diagnostics only.

Send Money API - Sandbox Mode

Endpoint

POST /api/v1/send-money

Same endpoint as production - Sandbox mode is automatically detected based on business settings

Request Body

{
    "amount": 10000,
    "phone_number": "+256712345678",
    "reference": "123e4567-e89b-12d3-a456-426614174000",
    "description": "Test send money payment",
    "callback_url": "https://your-webhook-url.com/callback",
    "country": "UG"
}

Sandbox Response

{
    "status": "success",
    "message": "Send money completed successfully (Sandbox Mode).",
    "data": {
        "transaction": {
            "uuid": "2c39fd0b-6610-55dd-c371-4b95f1d89087",
            "reference": "123e4567-e89b-12d3-a456-426614174000",
            "status": "sandbox",
            "provider_reference": "SANDBOX_AIRTEL_1758370330"
        },
        "send_money": {
            "amount": {
                "formatted": "10,000.00",
                "raw": 10000,
                "currency": "UGX"
            },
            "provider": "airtel",
            "phone_number": "+256712345678",
            "mode": "sandbox"
        },
        "timeline": {
            "initiated_at": "2025-09-20 15:12:10",
            "estimated_settlement": "N/A (Sandbox Mode)"
        },
        "metadata": {
            "response_timestamp": "2025-09-20 15:12:10",
            "sandbox_mode": true,
            "test_phone_number": false
        }
    }
}

Sandbox Callback Payload

When a callback_url is provided, the system will send a callback with this structure. Top-level metadata here is your optional merchant array from the create request (not sandbox diagnostics). 

{
    "event_type": "collection.completed",
    "transaction": {
        "uuid": "1b28ec9a-5509-44cc-b260-3a84f0c77976",
        "reference": "123e4567-e89b-12d3-a456-426614174000",
        "status": "completed",
        "amount": {
            "formatted": "5,000.00",
            "raw": 5000,
            "currency": "UGX"
        },
        "provider": "mtn",
        "phone_number": "+256712345678",
        "description": "Test collection payment",
        "created_at": "2025-09-20T12:12:10.000000Z",
        "updated_at": "2025-09-20T12:12:10.000000Z"
    },
    "collection": {
        "provider": "mtn",
        "phone_number": "+256712345678",
        "amount": {
            "formatted": "5,000.00",
            "raw": 5000,
            "currency": "UGX"
        },
        "mode": "sandbox",
        "provider_transaction_id": "SANDBOX_MTN_1758370330"
    },
    "metadata": [
        { "orderId": "ORD-123456789" },
        { "customerId": "customer@email.com", "isPII": true }
    ]
}

Key Features of Sandbox Mode

Safe Testing

  • • Test API functionality safely
  • • No impact on live data
  • • Perfect for development

Realistic Responses

  • • Production-like responses
  • • Proper callback handling
  • • Complete data formatting

Provider Support

  • • All supported providers
  • • Provider-specific responses
  • • Realistic test data

API Compatibility

  • • Same request format
  • • Same response structure
  • • Same validation rules

Testing with Webhooks

Using webhook.site for Testing

  1. 1. Go to webhook.site
  2. 2. Copy your unique webhook URL
  3. 3. Include it in your API request as callback_url
  4. 4. Make the API call
  5. 5. Check webhook.site to see the received callback

Example cURL Request

curl -X POST "https://your-domain.com/api/v1/collect-money" \
  -H "Authorization: Basic YOUR_API_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "phone_number": "+256712345678",
    "reference": "123e4567-e89b-12d3-a456-426614174000",
    "description": "Test collection",
    "callback_url": "https://webhook.site/your-unique-id",
    "country": "UG"
  }'

Note: This uses the same endpoint as production. Sandbox mode is automatically enabled based on your business configuration.

Important Notes

Default Configuration

Sandbox mode is enabled by default when a business signs up. No additional configuration is required to start testing.

Callback Testing

Callbacks are sent for testing purposes. Ensure your callback URL is accessible for proper testing.

Provider References

Sandbox provider references follow the format: SANDBOX_{PROVIDER}_{TIMESTAMP}. These are not real provider references and cannot be used for actual transactions.

Status Values

API response shows "status": "sandbox". Callback payload shows "status": "completed". This allows you to test both response handling and callback processing.

Chat on WhatsApp