Collections Guide

Overview

Collections allow you to request payments from customers via mobile money (MTN, Airtel) or card payments. For mobile money, the system detects the provider from the phone number and initiates the collection. For card, you receive a redirect_url and send the customer there to complete payment on the card gateway.

API Base URL

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

API Endpoints

Create Collection

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

Request Parameters

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

Card payments

To collect via card, send method = card. phone_number is not required. The API returns a redirect_url; send the customer to that URL (e.g. open in browser or redirect). They will complete payment on the card gateway, then be returned to your callback_url or the default return page.

Example request (card)

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,
    "method": "card",
    "reference": "123e4567-e89b-12d3-a456-426614174000",
    "country": "UG",
    "description": "Order payment"
  }'

Example response (card)

{
  "status": "success",
  "message": "Card collection initiated. Redirect the customer to redirect_url.",
  "data": {
    "transaction": {
      "uuid": "a799c628-f52a-4540-8b77-43509f2775d3",
      "reference": "b59d3d6d-5827-41ee-b455-18dd20ef1c8a",
      "status": "pending"
    },
    "redirect_url": "https://wallet.wearemarz.com/pay/card-gateway?reference=b59d3d6d-5827-41ee-b455-18dd20ef1c8a"
  }
}

Send the customer to data.redirect_url (e.g. open in same tab, new tab, or redirect). After payment they are sent to your callback_url or the default return page. Use webhooks or the transaction status API to confirm completion.

Provider Detection

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

Sandbox Mode

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

Webhooks & Callbacks

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

Best Practices