Send Money

Send Money (also known as disbursements or withdrawals) allows you to send payments to customers via mobile money. The provider is detected automatically from the phone number and country (Uganda MTN/Airtel, Kenya M-Pesa, Rwanda MTN/Airtel, DRC Vodacom/Airtel/Orange, Zambia MTN/Airtel/Zamtel, Cameroon MTN/Orange, Benin MTN/Moov, Côte d’Ivoire MTN/Orange, Gabon Airtel, Congo-Brazzaville MTN/Airtel, Senegal Orange/Free, Sierra Leone Orange).

How send money works

Create a request

Send a POST request to /api/v1/send-money with the amount and the recipient’s phone number.

Provider detected

The system automatically detects the mobile money provider for that market from the phone number.

Money transferred

Money is transferred directly to the recipient’s mobile money account.

Notification sent

The recipient receives an SMS notification of the incoming payment, and you receive a webhook with the result.

Pricing

Fees come from the public pricing page. Custom business rates may differ. Send money works in all 12 markets: UG, KE, RW, CD, ZM, CM, BJ, CI, GA, CG, SN, and SL. For DRC, also send currency as CDF or USD.

API endpoints

Method	Endpoint	Description
`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

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

Request parameters

Required fields

Field	Description
amount	Amount in the market currency (UGX, KES, RWF, CDF, USD, ZMW, XAF, XOF, or SLE)
phone_number	Recipient’s phone with country code
country	Country code (`UG`, `KE`, `RW`, `CD`, `ZM`, `CM`, `BJ`, `CI`, `GA`, `CG`, `SN`, or `SL`)
currency	Optional; required for DRC USD (`USD`). This is the wallet that is debited. Defaults by country (DRC → CDF)
reference	REQUIRED UUID format reference (e.g. `123e4567-e89b-12d3-a456-426614174000`)

Optional fields

Field	Description
description	Payment description (max 255 characters)
callback_url	Webhook URL (max 255 characters)
subscription_uuid	Optional. Pin the payout to a specific disbursement subscription from `GET /send-money/services`. For DRC, the subscription currency must match `currency`.
metadata	Optional array of objects to echo on create response and webhooks (max 10 items). Each item has one field name + value, and optional `isPII: true`. Example: `[{"orderId":"ORD-123"},{"customerId":"customer@email.com","isPII":true}]`

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 (Uganda)

Tab Title
Tab Title

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"' \
  --form 'metadata=[{"orderId":"ORD-123"},{"customerId":"customer@email.com","isPII":true}]'

const credentials = Buffer.from(`${apiKey}:${apiSecret}`).toString("base64");

const formData = new FormData();
formData.append("phone_number", "+256700000000");
formData.append("amount", "1000");
formData.append("country", "UG");
formData.append("description", "Payment to customer");
formData.append("callback_url", "https://your-app.com/webhook");
formData.append("reference", "123e4567-e89b-12d3-a456-426614174000");
formData.append("metadata", JSON.stringify([
  { orderId: "ORD-123" },
  { customerId: "customer@email.com", isPII: true },
]));

const response = await fetch("https://wallet.wearemarz.com/api/v1/send-money", {
  method: "POST",
  headers: { Authorization: `Basic ${credentials}` },
  body: formData,
});

const data = await response.json();
console.log(data);

Example request (Kenya / M-Pesa)

curl --location 'https://wallet.wearemarz.com/api/v1/send-money' \
  --header 'Authorization: Basic YOUR_API_CREDENTIALS' \
  --form 'phone_number="+254710000000"' \
  --form 'amount="100"' \
  --form 'country="KE"' \
  --form 'description="Payout to customer"' \
  --form 'callback_url="https://your-app.com/webhook"' \
  --form 'reference="123e4567-e89b-12d3-a456-426614174001"' \
  --form 'metadata=[{"orderId":"ORD-123"},{"customerId":"customer@email.com","isPII":true}]'

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.

MTN / Airtel (Uganda)

country: UG · +256
Auto-detected from phone number

M-Pesa (Kenya)

country: KE · +254

MTN / Airtel (Rwanda)

country: RW · +250

Vodacom / Airtel / Orange (DRC)

country: CD · CDF or USD · +243

Zambia / Cameroon

ZM · ZMW · +260 · Zambia
CM · XAF · +237 · Cameroon

West & Central Africa

BJ / CI / SN · XOF
GA / CG · XAF · SL · SLE

Sandbox mode

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

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

Webhooks & callbacks

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

Method	Description
Custom callback URL	Per-transaction callback URL for immediate notifications
Webhooks	Global webhook configuration for all transactions
Status updates	Final outcomes - `disbursement.completed` or `disbursement.failed`

Optional metadata: if you sent metadata on create, the same array is included at the top level of the callback payload (success and failure). Example callback payload

{
  "event_type": "disbursement.completed",
  "transaction": {
    "uuid": "4e7fb3fa-c13a-4b05-8acd-cf60ff68cb94",
    "reference": "system-generated-uuid",
    "provider_reference": "123e4567-e89b-12d3-a456-426614174000",
    "status": "completed",
    "amount": { "formatted": "1,000.00", "raw": 1000, "currency": "UGX" },
    "provider": "mtn",
    "phone_number": "+256700000000"
  },
  "disbursement": {
    "provider": "mtn",
    "phone_number": "+256700000000",
    "provider_transaction_id": "MTN_FINANCIAL_TRANSACTION_ID"
  },
  "metadata": [
    { "orderId": "ORD-123" },
    { "customerId": "customer@email.com", "isPII": true }
  ]
}

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

Withdrawal phone numbers (optional)

Withdrawal phone numbers are optional and provide an additional layer of security and convenience. If you have withdrawal phone numbers set up, you can only send money to those registered phone numbers. If you don’t have them configured, you can send money to any valid phone number (normal operation). Manage withdrawal phone numbers in your account settings.

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

Verified recipients

Never send money to unverified recipients.

Authentication

Implement proper authentication and authorization.

HTTPS

Use HTTPS for all API calls.

Monitoring

Monitor for suspicious transaction patterns.

Get started

Collections

Disbursements

Bills & airtime

Webhooks & platform

Build tools

Support

Send Money

How send money works

Pricing

API endpoints

Send money

Request parameters

Reference requirements

Example request (Uganda)

Example request (Kenya / M-Pesa)

Example response

Provider detection

MTN / Airtel (Uganda)

M-Pesa (Kenya)

MTN / Airtel (Rwanda)

Vodacom / Airtel / Orange (DRC)

Zambia / Cameroon

West & Central Africa

Sandbox mode

Webhooks & callbacks

Best practices

Phone number format

Withdrawal phone numbers (optional)

Amount limits

Error handling

Security considerations

Verified recipients

Authentication

HTTPS

Monitoring

​How send money works

​Pricing

​API endpoints

​Send money

​Request parameters

​Reference requirements

​Example request (Uganda)

​Example request (Kenya / M-Pesa)

​Example response

​Provider detection

MTN / Airtel (Uganda)

M-Pesa (Kenya)

MTN / Airtel (Rwanda)

Vodacom / Airtel / Orange (DRC)

Zambia / Cameroon

West & Central Africa

​Sandbox mode

​Webhooks & callbacks

​Best practices

​Phone number format

​Withdrawal phone numbers (optional)

​Amount limits

​Error handling

​Security considerations

Verified recipients

Authentication

HTTPS

Monitoring

How send money works

Pricing

API endpoints

Send money

Request parameters

Reference requirements

Example request (Uganda)

Example request (Kenya / M-Pesa)

Example response

Provider detection

Sandbox mode

Webhooks & callbacks

Best practices

Phone number format

Withdrawal phone numbers (optional)

Amount limits

Error handling

Security considerations