Sandbox Mode

Sandbox mode allows developers to test the MarzPay API in a safe testing environment without performing real financial transactions or affecting live data.

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 is required - sandbox mode is ready to use immediately after registration.

Same endpoint as production

Sandbox mode uses the same base URL as production. It is automatically detected based on your business settings. https://wallet.wearemarz.com/api/v1 Authentication is HTTP Basic: Authorization: Basic base64(api_key:api_secret).

Collect Money API - sandbox mode

Endpoint POST /api/v1/collect-money 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:

The 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": []
    },
    "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 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 sends a callback with this structure. If you enabled “Sign outgoing webhooks”, sandbox callbacks include the same X-MarzPay-Signature and X-MarzPay-Timestamp headers as live. 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" },
    "charge": { "formatted": "175.00", "raw": 175, "currency": "UGX" },
    "net_amount": { "formatted": "4,825.00", "raw": 4825, "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" },
    "charge": { "formatted": "175.00", "raw": 175, "currency": "UGX" },
    "net_amount": { "formatted": "4,825.00", "raw": 4825, "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 with no impact on live data. Perfect for development.

Realistic responses

Production-like responses, proper callback handling, and complete data formatting.

Provider support

All supported providers with provider-specific responses and realistic test data.

API compatibility

Same request format, same response structure, and same validation rules as production.

Testing with webhooks

Using webhook.site for testing:

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

Example cURL request

curl -X POST "https://wallet.wearemarz.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"
}'

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.

Sandbox transactions are simulated and do not move real money. Do not use sandbox keys in production or production keys in sandbox.

API Playground - Test sandbox endpoints live in the interactive API reference

Get started

Collections

Disbursements

Bills & airtime

Webhooks & platform

Build tools

Support

How sandbox mode works

Same endpoint as production

Collect Money API - sandbox mode

Send Money API - sandbox mode

Sandbox callback payload

Key features of sandbox mode

Safe testing

Realistic responses

Provider support

API compatibility

Testing with webhooks

Important notes

Default configuration

Callback testing

Provider references

Status values

​How sandbox mode works

​Same endpoint as production

​Collect Money API - sandbox mode

​Send Money API - sandbox mode

​Sandbox callback payload

​Key features of sandbox mode

Safe testing

Realistic responses

Provider support

API compatibility

​Testing with webhooks

​Important notes

​Default configuration

​Callback testing

​Provider references

​Status values

How sandbox mode works

Same endpoint as production

Collect Money API - sandbox mode

Send Money API - sandbox mode

Sandbox callback payload

Key features of sandbox mode

Testing with webhooks

Important notes

Default configuration

Callback testing

Provider references

Status values