Collections

Collect money from customers using mobile money. Customers pay with their phone number and you receive the funds in your main wallet, with webhooks confirming each completed collection. Collections work in all 12 markets: UG, KE, RW, CD, ZM, CM, BJ, CI, GA, CG, SN, and SL. For DRC you can collect in CDF or USD.

How collections work

Initialize collection

POST to /api/v1/collect-money with the customer’s phone number, amount, country, and a unique UUID reference.

Customer pays

The customer completes the payment on their mobile money provider (MTN, Airtel, M-Pesa, etc.).

Receive webhook

You receive a collection.completed webhook with the result, including the charge and net amount credited to your wallet.

API: Create a collection

Endpoint POST https://wallet.wearemarz.com/api/v1/collect-money Authentication is HTTP Basic: Authorization: Basic base64(api_key:api_secret). Request parameters

Parameter	Type	Required	Description
amount	number	Yes	Amount in local currency units (not cents), e.g. `5000` for UGX 5,000
phone_number	string	Yes	Customer’s phone with country code, e.g. `+256700000000`
country	string	Yes	Market code: `UG`, `KE`, `RW`, `CD`, `ZM`, `CM`, `BJ`, `CI`, `GA`, `CG`, `SN`, or `SL`
reference	string	Yes	Unique UUID v4 reference for idempotency
method	string	No	Set to `mobile_money` (default) for mobile money collections
currency	string	No	Currency code; required for DRC (`CDF` or `USD`)
description	string	No	Description for the payment (max 255 characters)
callback_url	string	No	URL to receive the server-to-server callback after payment
metadata	array	No	Optional merchant array echoed on create and webhooks, max 10 items

Do not send phone_number for card payments - see Card Payments. Example request

Tab Title
Tab Title

curl -X POST 'https://wallet.wearemarz.com/api/v1/collect-money' \
  -H 'Authorization: Basic YOUR_BASE64_API_CREDENTIALS' \
  -H 'Content-Type: application/json' \
  -d '{
  "amount": 5000,
  "phone_number": "+256700000000",
  "reference": "123e4567-e89b-12d3-a456-426614174000",
  "country": "UG",
  "description": "Payment for services",
  "callback_url": "https://your-app.com/webhooks/collections",
  "metadata": [
    { "orderId": "ORD-123456789" },
    { "customerId": "customer@email.com", "isPII": true }
  ]
}'

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

const response = await fetch("https://wallet.wearemarz.com/api/v1/collect-money", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Basic ${credentials}`,
  },
  body: JSON.stringify({
    amount: 5000,
    phone_number: "+256700000000",
    reference: "123e4567-e89b-12d3-a456-426614174000",
    country: "UG",
    description: "Payment for services",
    callback_url: "https://your-app.com/webhooks/collections",
    metadata: [
      { orderId: "ORD-123456789" },
      { customerId: "customer@email.com", isPII: true },
    ],
  }),
});

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

Example response

{
  "status": "success",
  "message": "Collection initiated successfully.",
  "data": {
    "transaction": {
      "uuid": "4e7aba5d-4681-4acc-91b6-4744228fcbcd",
      "reference": "123e4567-e89b-12d3-a456-426614174000",
      "status": "pending",
      "provider_reference": "MTN_REF_123456789"
    },
    "collection": {
      "amount": {
        "formatted": "5,000.00",
        "raw": 5000,
        "currency": "UGX"
      },
      "provider": "mtn",
      "phone_number": "+256700000000",
      "mode": "live"
    }
  }
}

Amount, charge, and net amount

All amounts are in local currency units (not cents). On completion the response includes:

Field	Meaning
`amount`	Total collected from the customer
`charge`	Fee deducted for the collection
`net_amount`	Amount credited to your main wallet (`amount - charge`)

You only pay on successful collections - failed or pending collections cost nothing. See Public Pricing for current rates.

Wallets

Mobile money collections are credited to your main wallet. Card payment collections go to a separate card wallet. See Bank Transfer for withdrawing funds with wallet_source.

New accounts start in sandbox mode where you can test collections without processing real payments. See Sandbox Mode.

Use a unique UUID v4 reference for every collection. Reusing a reference will be rejected.

Get started

Disbursements

Bills & airtime

Webhooks & platform

Build tools

Support

Collections

How collections work

API: Create a collection

Amount, charge, and net amount

Wallets

​How collections work

​API: Create a collection

​Amount, charge, and net amount

​Wallets

How collections work

API: Create a collection

Amount, charge, and net amount

Wallets