API Reference

Complete API documentation for Marz Pay payment platform

API Overview

Base URL

https://wallet.wearemarz.com/api/v1/v1

Authentication

API Key (Basic Auth)

Content Type

application/json

Authentication

All API requests require authentication using your API key in the Authorization header with Basic Auth format. 

Authorization: Basic YOUR_API_CREDENTIALS

Format: YOUR_API_CREDENTIALS = base64_encode("your_api_key:your_api_secret")

Available Endpoints

Balance API

  • GET /api/v1/balance - Get account overview with summaries

Collect Money API

  • POST /api/v1/collect-money - Create collection
  • GET /api/v1/collect-money/services - List available countries
  • GET /api/v1/collect-money/{uuid} - Get collection details

Send Money API

  • POST /api/v1/send-money - Send money to recipient
  • GET /api/v1/send-money/services - List available services
  • GET /api/v1/send-money/{uuid} - Get send money details

Transactions API

  • GET /api/v1/transactions - List transactions
  • GET /api/v1/transactions/{uuid} - Get transaction details

Services API

  • GET /api/v1/services - List services
  • GET /api/v1/services/{uuid} - Get service details

Account API

  • GET /api/v1/account - Get account details
  • PUT /api/v1/account - Update account

Webhooks API

  • GET /api/v1/webhooks - List webhooks
  • POST /api/v1/webhooks - Create webhook
  • GET /api/v1/webhooks/{uuid} - Get webhook details
  • PUT /api/v1/webhooks/{uuid} - Update webhook
  • DELETE /api/v1/webhooks/{uuid} - Delete webhook

Live API Examples

Balance API

Get account balance and summary information with secure field mapping.

Request

curl -X GET "https://wallet.wearemarz.com/api/v1/v1/balance" \
  -H "Authorization: Basic YOUR_API_CREDENTIALS" \
  -H "Content-Type: application/json"

Response

{
  "status": "success",
  "data": {
          "account": {
        "uuid": "8f6cdf42-44e1-4f9f-a359-09721bb32111",
        "business_name": "MarzPay Business",
      "balance": {
        "formatted": "2,503,899.02",
        "raw": 2503899.02,
        "currency": "UGX"
      },
      "status": {
        "mode": "live",
        "account_status": "active",
        "is_frozen": false
      }
    },
    "summary": {
      "monthly": {
        "credits": "50,000.00",
        "debits": "25,000.00",
        "net_change": "25,000.00",
        "transaction_count": 15
      }
    }
  }
}

Services API

Get available payment services and subscription status with enhanced security.

List Services

Request
curl -X GET "https://wallet.wearemarz.com/api/v1/v1/services?type=collection&provider=mtn&status=active" \
  -H "Authorization: Basic YOUR_API_CREDENTIALS" \
  -H "Content-Type: application/json"
Response
{
  "status": "success",
  "data": {
    "account": {
      "uuid": "8f6cdf42-44e1-4f9f-a359-09721bb32111"
    },
    "services": [
      {
        "service": {
          "uuid": "service-uuid-123",
          "name": "MTN Mobile Money Collection",
          "provider": "MTN",
          "type": "collection",
          "description": "Collect payments via MTN Mobile Money",
          "currency": "UGX",
          "mode": "live",
          "is_active": true
        },
        "subscription": {
          "uuid": "sub-uuid-456",
          "status": "active",
          "subscribed_at": "2024-01-15 10:30:00",
          "expires_at": null
        },
        "availability": {
          "is_subscribed": true,
          "can_subscribe": false
        }
      }
    ],
    "summary": {
      "total_services": 1,
      "subscribed_services": 1,
      "available_services": 0
    },
    "filters": {
      "type": "collection",
      "provider": "mtn",
      "status": "active"
    },
    "metadata": {
      "response_timestamp": "2024-01-20 15:00:00"
    }
  }
}

🔍 Get Service Details

Request
curl -X GET "https://wallet.wearemarz.com/api/v1/services/service-uuid-123" \
  -H "Authorization: Basic YOUR_API_CREDENTIALS" \
  -H "Content-Type: application/json"
Response
{
  "status": "success",
  "data": {
    "account": {
      "uuid": "8f6cdf42-44e1-4f9f-a359-09721bb32111"
    },
    "service": {
      "uuid": "service-uuid-123",
      "name": "MTN Mobile Money Collection",
      "provider": "MTN",
      "type": "collection",
      "description": "Collect payments via MTN Mobile Money",
      "currency": "UGX",
      "mode": "live",
      "is_active": true,
      "created_at": "2024-01-01 00:00:00",
      "updated_at": "2024-01-15 10:30:00"
    },
    "subscription": {
      "uuid": "sub-uuid-456",
      "status": "active",
      "subscribed_at": "2024-01-15 10:30:00",
      "expires_at": null,
      "notes": "Production subscription",
      "settings": {
        "webhook_url": "https://your-app.com/webhooks",
        "auto_retry": true
      }
    },
    "availability": {
      "is_subscribed": true,
      "can_subscribe": false,
      "subscription_required": true
    },
    "metadata": {
      "response_timestamp": "2024-01-20 15:00:00"
    }
  }
}
Query Parameters
Service Type
  • type - collection, withdrawal
Provider
  • provider - mtn, airtel
Status
  • status - active, inactive
Error Examples
Validation Error (422 Unprocessable Entity)
{
  "status": "error",
  "message": "Please check your input and try again.",
  "error_code": "VALIDATION_ERROR"
}
Service Not Found (404 Not Found)
{
  "status": "error",
  "message": "Service not found.",
  "error_code": "SERVICE_NOT_FOUND"
}

Transactions API

Get transaction history and details with comprehensive filtering.

List Transactions

Request
curl -X GET "https://wallet.wearemarz.com/api/v1/transactions?per_page=10&type=collection&status=successful&provider=mtn&start_date=2024-01-01&end_date=2024-01-31" \
  -H "Authorization: Basic YOUR_API_CREDENTIALS" \
  -H "Content-Type: application/json"
Response
{
  "status": "success",
  "data": {
    "account": {
      "uuid": "8f6cdf42-44e1-4f9f-a359-09721bb32111",
      "current_balance": {
        "formatted": "2,503,899.02",
        "raw": 2503899.02,
        "currency": "UGX"
      }
    },
    "transactions": [
      {
        "uuid": "5cbe2960-971e-46b0-ac32-2c32ad0c496f",
        "reference": "COL001",
        "provider_reference": "MTN_20240120_001",
        "amount": {
          "formatted": "1,000.00",
          "raw": 1000,
          "currency": "UGX"
        },
        "type": "collection",
        "status": "successful",
        "description": "Payment received from customer",
        "provider": "MTN",
        "phone_number": "+256781230949",
        "payment_link": {
          "uuid": "link-uuid-123",
          "title": "Invoice Payment"
        },
        "timeline": {
          "created_at": "2024-01-20 14:30:00",
          "updated_at": "2024-01-20 14:35:00"
        }
      }
    ],
    "pagination": {
      "current_page": 1,
      "last_page": 5,
      "per_page": 10,
      "total": 50,
      "from": 1,
      "to": 10
    },
    "filters": {
      "type": "collection",
      "status": "successful",
      "provider": "mtn",
      "start_date": "2024-01-01",
      "end_date": "2024-01-31"
    },
    "metadata": {
      "response_timestamp": "2024-01-20 15:00:00"
    }
  }
}

Get Transaction Details

Request
curl -X GET "https://wallet.wearemarz.com/api/v1/transactions/5cbe2960-971e-46b0-ac32-2c32ad0c496f" \
  -H "Authorization: Basic YOUR_API_CREDENTIALS" \
  -H "Content-Type: application/json"
Response
{
  "status": "success",
  "data": {
    "account": {
      "uuid": "8f6cdf42-44e1-4f9f-a359-09721bb32111"
    },
    "transaction": {
      "uuid": "5cbe2960-971e-46b0-ac32-2c32ad0c496f",
      "reference": "COL001",
      "provider_reference": "MTN_20240120_001",
      "amount": {
        "formatted": "1,000.00",
        "raw": 1000,
        "currency": "UGX"
      },
      "type": "collection",
      "status": "successful",
      "description": "Payment received from customer",
      "origin": "api",
      "method": "mobile_money",
      "transaction_for": "payment_link"
    },
    "details": {
      "provider": "MTN",
      "phone_number": "+256781230949",
      "names": "John Doe",
      "email": "john@example.com",
      "ip_address": "192.168.1.1",
      "user_agent": "Mozilla/5.0..."
    },
    "service": {
      "subscription": {
        "uuid": "sub-uuid-456",
        "status": "active"
      },
      "service": {
        "uuid": "service-uuid-123",
        "name": "MTN Mobile Money Collection",
        "provider": "MTN",
        "description": "Collect payments via MTN Mobile Money"
      }
    },
    "payment_link": {
      "uuid": "link-uuid-123",
      "title": "Invoice Payment",
      "reference": "INV001"
    },
    "charge_transaction": {
      "uuid": "charge-uuid-789",
      "amount": {
        "formatted": "30.00",
        "raw": 30
      },
      "status": "successful"
    },
    "timeline": {
      "created_at": "2024-01-20 14:30:00",
      "updated_at": "2024-01-20 14:35:00"
    },
    "metadata": {
      "response_timestamp": "2024-01-20 15:00:00"
    }
  }
}
Query Parameters
Pagination
  • page - Page number (default: 1)
  • per_page - Items per page (1-100, default: 25)
Filtering
  • type - collection, withdrawal, charge, refund
  • status - pending, processing, successful, failed, cancelled
  • provider - mtn, airtel
  • start_date - YYYY-MM-DD format
  • end_date - YYYY-MM-DD format
  • reference - Transaction reference (max 100 chars)
Error Examples
Validation Error (422 Unprocessable Entity)
{
  "status": "error",
  "message": "Please check your input and try again.",
  "error_code": "VALIDATION_ERROR"
}
Transaction Not Found (404 Not Found)
{
  "status": "error",
  "message": "Transaction not found.",
  "error_code": "TRANSACTION_NOT_FOUND"
}

Collection API

Initiate mobile money collections from customers. Provider is automatically detected from phone number patterns.

Create Collection

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": 1000,
    "phone_number": "+256781230949",
    "country": "UG",
    "reference": "c97fae8b-9b7f-4192-9f72-6f0859d33e67",
    "description": "Payment for services",
    "callback_url": "https://your-app.com/marz/callback"
  }'
Response
{
  "status": "success",
  "message": "Collection initiated successfully.",
  "data": {
    "transaction": {
      "uuid": "4e7fb3fa-c13a-4b05-8acd-cf60ff68cb94",
      "reference": "COL1703123456789abc",
      "status": "processing",
      "provider_reference": null
    },
    "collection": {
      "amount": {
        "formatted": "1,000.00",
        "raw": 1000,
        "currency": "UGX"
      },
      "provider": "mtn",
      "phone_number": "+256781230949",
      "mode": "live"
    },
    "timeline": {
      "initiated_at": "2024-01-20 14:30:00",
      "estimated_settlement": "2024-01-20 14:35:00"
    },
    "metadata": {
      "response_timestamp": "2024-01-20 14:30:00",
      "sandbox_mode": false
    }
  }
}

Get Available Services

Request
curl -X GET "https://wallet.wearemarz.com/api/v1/collect-money/services" \
  -H "Authorization: Basic YOUR_API_CREDENTIALS" \
  -H "Content-Type: application/json"
Response
{
  "status": "success",
  "data": {
    "account": {
      "uuid": "8f6cdf42-44e1-4f9f-a359-09721bb32111"
    },
    "countries": {
      "UG": {
        "country_code": "UG",
        "country_name": "Uganda",
        "providers": [
          {
            "provider": "MTN",
            "name": "MTN Mobile Money Collection",
            "currency": "UGX",
            "mode": "live",
            "subscription_uuid": "sub-uuid-456"
          },
          {
            "provider": "AIRTEL",
            "name": "Airtel Money Collection",
            "currency": "UGX",
            "mode": "live",
            "subscription_uuid": "sub-uuid-789"
          }
        ],
        "total_providers": 2
      }
    },
    "summary": {
      "total_countries": 1,
      "total_services": 2
    },
    "metadata": {
      "response_timestamp": "2024-01-20 14:30:00"
    }
  }
}

Get Collection Details

Request
curl -X GET "https://wallet.wearemarz.com/api/v1/collect-money/4e7fb3fa-c13a-4b05-8acd-cf60ff68cb94" \
  -H "Authorization: Basic YOUR_API_CREDENTIALS" \
  -H "Content-Type: application/json"
Response
{
  "status": "success",
  "data": {
    "transaction": {
      "uuid": "4e7fb3fa-c13a-4b05-8acd-cf60ff68cb94",
      "reference": "COL1703123456789abc",
      "status": "successful",
      "provider_reference": "MTN_20240120_001"
    },
    "collection": {
      "amount": {
        "formatted": "1,000.00",
        "raw": 1000,
        "currency": "UGX"
      },
      "provider": "MTN",
      "phone_number": "+256781230949",
      "description": "Payment for services"
    },
    "timeline": {
      "created_at": "2024-01-20 14:30:00",
      "updated_at": "2024-01-20 14:35:00"
    },
    "metadata": {
      "response_timestamp": "2024-01-20 14:30:00"
    }
  }
}
Request Parameters
Required Fields
  • amount - Amount in UGX (500 - 10,000,000)
  • phone_number - Phone with country code (+256xxxxxxxxx)
  • country - Country code (UG)
  • reference - REQUIRED UUID format reference (e.g., 123e4567-e89b-12d3-a456-426614174000)
Optional Fields
  • description - Payment description (max 255 chars)
  • callback_url - Webhook URL (max 255 chars)
Reference Requirements

API Collections require a valid UUID reference:

  • Must be in UUID v4 format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
  • Must be unique across all API collections
  • Cannot be reused - each collection needs a unique reference
  • Maximum 50 characters
Valid UUID Examples:
c97fae8b-9b7f-4192-9f72-6f0859d33e67
123e4567-e89b-12d3-a456-426614174000
550e8400-e29b-41d4-a716-446655440000
🛡️ Duplicate Reference Protection

The system prevents duplicate references for API collections:

  • Each reference can only be used once per API collection
  • Attempts to reuse a reference will return a DUPLICATE_REFERENCE error
  • All duplicate attempts are logged for security audit
Duplicate Reference Error:
{ "status": "error", "message": "Reference already exists for API collection. Please use a different reference.", "error_code": "DUPLICATE_REFERENCE" }
Auto-Generation for Other Methods

Note: While API collections require manual UUID references, other collection methods automatically generate references:

  • Payment Links: Auto-generate UUIDs when customers make payments
  • Interface Collections: Auto-generate UUIDs for web form submissions
  • API Collections: Require user-provided UUIDs (as shown above)
Auto-Generated Reference Example:
ab377eaf-4253-451e-b7bf-0a3295f4486b
Error Examples
Missing Required Reference (422 Unprocessable Entity)
{
  "status": "error",
  "message": "The given data was invalid.",
  "errors": {
    "reference": ["Reference is required and must be a valid UUID format."]
  }
}
Invalid UUID Format (422 Unprocessable Entity)
{
  "status": "error",
  "message": "The given data was invalid.",
  "errors": {
    "reference": ["Reference must be a valid UUID format (e.g., 123e4567-e89b-12d3-a456-426614174000)."]
  }
}
Duplicate Reference (422 Unprocessable Entity)
{
  "status": "error",
  "message": "Reference already exists for API collection. Please use a different reference.",
  "error_code": "DUPLICATE_REFERENCE"
}
Invalid Phone Number Format (422 Unprocessable Entity)
{
  "status": "error",
  "message": "Invalid Airtel phone number format. Must be 9 digits (without country code).",
  "error_code": "INVALID_PHONE_FORMAT"
}
Sandbox Mode

When a service is configured with sandbox environment, the API will:

  • Skip actual provider API calls
  • Return immediate success response
  • Generate sandbox provider references
  • Set status to "sandbox"
Sandbox Response:
status: "sandbox"
provider_reference: "SANDBOX_MTN_1234567890"
estimated_settlement: "N/A (Sandbox Mode)"

Transactions API

Request

curl -X GET "https://wallet.wearemarz.com/api/v1/transactions?per_page=5&type=credit" \
  -H "Authorization: Basic YOUR_API_CREDENTIALS" \
  -H "Content-Type: application/json"

Response

{
  "status": "success",
  "data": {
    "account": {
      "uuid": "8f6cdf42-44e1-4f9f-a359-09721bb32111",
      "current_balance": {
        "formatted": "2,503,899.02",
        "raw": 2503899.02,
        "currency": "UGX"
      }
    },
    "transactions": [
      {
        "uuid": "5cbe2960-971e-46b0-ac32-2c32ad0c496f",
        "reference": "COL001",
        "amount": {
          "formatted": "1,000.00",
          "raw": 1000,
          "currency": "UGX"
        },
        "type": "credit",
        "status": "successful",
        "description": "Payment received",
        "provider": "MTN",
        "phone_number": "+256700000000",
        "timeline": {
          "created_at": "2025-08-17 04:57:25",
          "updated_at": "2025-08-17 04:57:25"
        }
      }
    ],
    "pagination": {
      "current_page": 1,
      "last_page": 25,
      "per_page": 5,
      "total": 50
    }
  }
}

Webhooks API

Request

curl -X POST "https://wallet.wearemarz.com/api/v1/webhooks" \
  -H "Authorization: Basic YOUR_API_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Transaction Webhook",
    "url": "https://your-domain.com/webhook",
    "event_type": "success",
    "is_active": true
  }'

Response

{
  "status": "success",
  "message": "Webhook created successfully.",
  "data": {
    "webhook": {
      "uuid": "c00f349b-5759-475f-96c9-57e118a39ae2",
      "name": "Transaction Webhook",
      "url": "https://your-domain.com/webhook",
      "event_type": "success",
      "is_active": true,
      "retry_count": 0,
      "timeline": {
        "created_at": "2025-08-19 17:43:43",
        "updated_at": "2025-08-19 17:43:43"
      }
    }
  }
}

Error Handling

Error Response Format

{
  "status": "error",
  "message": "Human readable error message",
  "error_code": "SPECIFIC_ERROR_CODE"
}

Account API

Manage your account details with secure field mapping. Only safe fields can be updated.

Get Account Details

Request
curl -X GET "https://wallet.wearemarz.com/api/v1/account" \
  -H "Authorization: Basic YOUR_API_CREDENTIALS" \
  -H "Content-Type: application/json"
Response
{
  "status": "success",
  "data": {
    "account": {
      "uuid": "8f6cdf42-44e1-4f9f-a359-09721bb32111",
      "business_name": "Acme Corporation",
      "email": "admin@acme.com",
      "contact_phone": "+256700000000",
      "business_address": "123 Main Street",
      "business_city": "Kampala",
      "business_country": "Uganda",
      "balance": {
        "formatted": "2,503,899.02",
        "raw": 2503899.02,
        "currency": "UGX"
      },
      "status": {
        "account_status": "active",
        "is_frozen": false,
        "freeze_reason": null,
        "is_verified": true
      },
      "limits": {
        "withdrawal": {
          "minimum": { "formatted": "1,000.00", "raw": 1000 },
          "maximum": { "formatted": "10,000,000.00", "raw": 10000000 }
        },
        "deposit": {
          "minimum": { "formatted": "100.00", "raw": 100 },
          "maximum": { "formatted": "50,000,000.00", "raw": 50000000 }
        }
      },
      "charges": {
        "percentage_charge": 3.0,
        "fixed_charge": { "formatted": "0.00", "raw": 0 }
      },
      "timeline": {
        "created_at": "2024-01-15 10:30:00",
        "updated_at": "2024-01-20 14:45:00",
        "last_login_at": "2024-01-20 14:45:00"
      }
    },
    "metadata": {
      "response_timestamp": "2024-01-20 14:45:00"
    }
  }
}

Update Account Details

Request
curl -X PUT "https://wallet.wearemarz.com/api/v1/account" \
  -H "Authorization: Basic YOUR_API_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -d '{
    "business_name": "Acme Corporation Ltd",
    "contact_phone": "+256700000001",
    "business_address": "456 Business Avenue",
    "business_city": "Kampala",
    "business_country": "Uganda"
  }'
Response
{
  "status": "success",
  "message": "Account updated successfully.",
  "data": {
    "account": {
      "uuid": "8f6cdf42-44e1-4f9f-a359-09721bb32111",
      "business_name": "Acme Corporation Ltd",
      "contact_phone": "+256700000001",
      "business_address": "456 Business Avenue",
      "business_city": "Kampala",
      "business_country": "Uganda",
      "updated_at": "2024-01-20 15:30:00"
    },
    "metadata": {
      "response_timestamp": "2024-01-20 15:30:00"
    }
  }
}
Error Examples
Sensitive Field Update Attempt (403 Forbidden)
{
  "status": "error",
  "message": "Cannot update sensitive account fields through this endpoint.",
  "error_code": "SENSITIVE_FIELD_UPDATE_BLOCKED"
}
Validation Error (422 Unprocessable Entity)
{
  "status": "error",
  "message": "Validation failed.",
  "errors": {
    "business_name": ["Business name cannot exceed 255 characters."],
    "contact_phone": ["Phone number cannot exceed 20 characters."]
  }
}

Common HTTP Status Codes

Success Codes

  • 200 - OK (GET, PUT, DELETE)
  • 201 - Created (POST)

Error Codes

  • 400 - Bad Request
  • 401 - Unauthorized
  • 403 - Forbidden
  • 404 - Not Found
  • 422 - Validation Error
  • 500 - Internal Server Error

Getting Started

1. Get Your API Credentials

Log into your dashboard and navigate to the API section to generate your API key and secret.

2. Test Your Connection

Use the following curl command to test your API connection: 

curl -X GET "https://wallet.wearemarz.com/api/v1/balance" \
  -H "Authorization: Basic YOUR_API_CREDENTIALS" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

3. Start Building

Explore the available endpoints and start integrating payments into your application.