MarzPay API Documentation

Overview

Collections allow you to request payments from customers via mobile money. The system automatically detects the mobile money provider (MTN or Airtel) based on the phone number and initiates the collection process.

How Collections Work

You create a collection request with amount and customer's phone number
System automatically detects the mobile money provider (MTN/Airtel)
Customer receives a USSD prompt or SMS notification
Customer approves or declines the payment
You receive a webhook notification with the result

API Base URL

All collections API requests should be made to the following base URL:

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

API Endpoints

POST /api/v1/collect-money Create a collection

GET /api/v1/collect-money/services Get available services

GET /api/v1/collect-money/{uuid} Get collection details

Create Collection

To create a collection, send a POST request to the collection endpoint with the required parameters.

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

Example Request

curl --location 'https://wallet.wearemarz.com/api/v1/collect-money' \
--header 'Authorization: Basic YOUR_API_CREDENTIALS' \
--form 'phone_number="+256700000000"' \
--form 'amount="1000"' \
--form 'country="UG"' \
--form 'reference="123e4567-e89b-12d3-a456-426614174000"' \
--form 'description="Payment for services"' \
--form 'callback_url="https://your-app.com/webhook"'

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

Provider Detection

The system automatically detects the mobile money provider based on the phone number pattern.

Supported Providers

MTN Mobile Money

0760-0780, 077, 078, 031, 039
Automatic detection from phone number

Airtel Money

0700-0750
Automatic detection from phone number

Sandbox Mode

New accounts start in sandbox mode where you can test all collection features without processing real payments or creating actual transactions.

Sandbox Features

No actual mobile money API calls are made
No real transactions are created in the database
Immediate dummy success response
Generated sandbox provider references
Status set to "sandbox"
Perfect for development and testing

Webhooks & Callbacks

You can receive real-time notifications about collection status through webhooks or custom callback URLs.

Notification Methods

Custom Callback URL: Per-transaction callback URL for immediate notifications
Webhooks: Global webhook configuration for all transactions
Status Updates: Real-time status changes (pending, processing, successful, failed)

Best Practices

Phone Number Format

Always include country code (+256 for Uganda)
Use the format: +256xxxxxxxxx
Ensure the number is active and registered for mobile money

Amount Limits

Minimum amount: 500 UGX
Maximum amount: 10,000,000 UGX
Consider customer's mobile money limits

Error Handling

Always check the response status
Handle failed collections gracefully
Implement retry logic for failed requests
Monitor webhook delivery and implement fallbacks

Collections Guide