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"
}

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"
        },
        "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
        }
    }
}

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:

{
    "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_reference": "SANDBOX_MTN_1758370330"
    },
    "business": {
        "uuid": "5ed723af-456a-47d6-9791-e4ffe478a462",
        "name": "Your Business Name"
    },
    "metadata": {
        "sandbox_mode": true,
        "environment": "test",
        "timestamp": "2025-09-20T12:12:10.327098Z",
        "webhook_id": null
    }
}

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. Go to webhook.site
2. Copy your unique webhook URL
3. Include it in your API request as callback_url
4. Make the API call
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.