Send Money Guide

Learn how to send money to customers using mobile money with Marz Pay

Overview

Send Money (also known as disbursements or withdrawals) allows you to send payments to customers via mobile money. The system automatically detects the mobile money provider (MTN or Airtel) based on the phone number and initiates the disbursement process.

How Send Money Works

  1. You create a send money request with amount and recipient's phone number
  2. System automatically detects the mobile money provider (MTN/Airtel)
  3. Money is transferred directly to the recipient's mobile money account
  4. Recipient receives SMS notification of the incoming payment
  5. You receive a webhook notification with the result

API Base URL

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

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

API Endpoints

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

Send Money

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

Request Parameters

Required Fields

  • amount - Amount in UGX (500 - 10,000,000)
  • phone_number - Recipient's 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 Send Money requires a valid UUID reference:

  • Must be in UUID v4 format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx
  • Must be unique across all API send money transactions
  • Cannot be reused - each transaction 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/send-money' \
--header 'Authorization: Basic YOUR_API_CREDENTIALS' \
--form 'phone_number="+256700000000"' \
--form 'amount="1000"' \
--form 'country="UG"' \
--form 'description="Payment to customer"' \
--form 'callback_url="https://your-app.com/webhook"' \
--form 'reference="123e4567-e89b-12d3-a456-426614174000"'

Example Response

{
  "status": "success",
  "message": "Send money initiated successfully.",
  "data": {
    "transaction": {
      "uuid": "4e7fb3fa-c13a-4b05-8acd-cf60ff68cb94",
      "reference": "123e4567-e89b-12d3-a456-426614174000",
      "status": "processing",
      "provider_reference": "MTN_REF_123456789"
    },
    "disbursement": {
      "amount": {
        "formatted": "1,000.00",
        "raw": 1000,
        "currency": "UGX"
      },
      "provider": "airtel",
      "phone_number": "+256700000000",
      "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, 079, 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 send money 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 send money 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
  • Verify recipient details before sending large amounts

Amount Limits

  • Minimum amount: 500 UGX
  • Maximum amount: 10,000,000 UGX
  • Consider recipient's mobile money limits
  • Check your account balance before sending

Error Handling

  • Always check the response status
  • Handle failed send money requests gracefully
  • Implement retry logic for failed requests
  • Monitor webhook delivery and implement fallbacks
  • Keep transaction logs for audit purposes

Security Considerations

  • Never send money to unverified recipients
  • Implement proper authentication and authorization
  • Use HTTPS for all API calls
  • Monitor for suspicious transaction patterns
  • Keep API credentials secure and rotate regularly