Quickstart

This page takes you from a new business account to a collection that settles into your wallet. Everything below runs against sandbox until your business verification is approved.

1. Create your account

Open the MarzPay dashboard and choose Get Started. Use a business email you can access, because verification links go there.

Complete onboarding

Add your business details and upload the documents in your onboarding checklist: business registration, tax ID, directors’ IDs, and proof of address. Most reviews finish in one to three business days.

Subscribe to a service

Open the marketplace in the dashboard and subscribe to the collection and disbursement services for the markets you need, for example Uganda MTN collection or Kenya M-Pesa disbursement. Endpoints return SERVICE_NOT_SUBSCRIBED until you do.

New businesses start in sandbox mode. You can call every endpoint immediately, with dummy responses, while verification is still in review.

2. Generate API credentials

Open API Keys in the dashboard.
Click Generate New API Key and give it a name your team will recognise.
Copy the key and the secret. The secret is shown once.

The API uses HTTP Basic authentication:

Authorization: Basic base64_encode("YOUR_API_KEY:YOUR_API_SECRET")

In a shell, build the header once:

# macOS / Linux
echo -n "your_api_key:your_api_secret" | base64

# Windows PowerShell
[Convert]::ToBase64String([Text.Encoding]::UTF8.GetBytes("your_api_key:your_api_secret"))

Keep credentials on the server. Never ship the secret in a mobile app, browser bundle, or public repo, and rotate the key from the dashboard if it leaks.

3. Know your base URL

Environment	Base URL
Production	`https://wallet.wearemarz.com/api/v1`
Sandbox	Same URL, routed to sandbox by your business settings

There is no separate sandbox host. The dashboard setting decides whether a request creates a live transaction or a sandbox one.

POST https://wallet.wearemarz.com/api/v1/collect-money
GET  https://wallet.wearemarz.com/api/v1/balance
GET  https://wallet.wearemarz.com/api/v1/transactions

4. Collect money

Send an amount, a phone number with the country code, a country, and a unique UUID reference.

cURL
Node.js
PHP
Python

curl -X POST https://wallet.wearemarz.com/api/v1/collect-money \
  -H 'Authorization: Basic YOUR_BASE64_CREDENTIALS' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 1000,
    "phone_number": "+256700000000",
    "country": "UG",
    "reference": "123e4567-e89b-12d3-a456-426614174000",
    "description": "Payment for services",
    "callback_url": "https://your-app.com/webhooks/marzpay"
  }'

const credentials = Buffer.from(
  `${process.env.MARZPAY_KEY}:${process.env.MARZPAY_SECRET}`
).toString("base64");

const response = await fetch("https://wallet.wearemarz.com/api/v1/collect-money", {
  method: "POST",
  headers: {
    Authorization: `Basic ${credentials}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 1000,
    phone_number: "+256700000000",
    country: "UG",
    reference: crypto.randomUUID(),
    description: "Payment for services",
    callback_url: "https://your-app.com/webhooks/marzpay",
  }),
});

console.log(await response.json());

$credentials = base64_encode(env('MARZPAY_KEY') . ':' . env('MARZPAY_SECRET'));

$ch = curl_init('https://wallet.wearemarz.com/api/v1/collect-money');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    'Authorization: Basic ' . $credentials,
    'Content-Type: application/json',
  ],
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 1000,
    'phone_number' => '+256700000000',
    'country' => 'UG',
    'reference' => '123e4567-e89b-12d3-a456-426614174000',
    'description' => 'Payment for services',
  ]),
]);

echo curl_exec($ch);
curl_close($ch);

import base64, os, requests

credentials = base64.b64encode(
    f"{os.environ['MARZPAY_KEY']}:{os.environ['MARZPAY_SECRET']}".encode()
).decode()

response = requests.post(
    "https://wallet.wearemarz.com/api/v1/collect-money",
    headers={"Authorization": f"Basic {credentials}"},
    json={
        "amount": 1000,
        "phone_number": "+256700000000",
        "country": "UG",
        "reference": "123e4567-e89b-12d3-a456-426614174000",
        "description": "Payment for services",
    },
    timeout=30,
)

print(response.json())

201 Created

{
  "status": "success",
  "message": "Collection initiated successfully.",
  "data": {
    "transaction": {
      "uuid": "4e7fb3fa-c13a-4b05-8acd-cf60ff68cb94",
      "reference": "123e4567-e89b-12d3-a456-426614174000",
      "status": "processing",
      "provider_reference": null
    },
    "collection": {
      "amount": { "formatted": "1,000.00", "raw": 1000, "currency": "UGX" },
      "provider": "mtn",
      "phone_number": "+256700000000",
      "mode": "live"
    },
    "timeline": {
      "initiated_at": "2024-01-20 14:30:00",
      "estimated_settlement": "2024-01-20 14:35:00"
    }
  }
}

The customer gets a prompt on their phone. When they approve it, a callback lands on your callback_url with event_type: "collection.completed" and the provider transaction ID.

provider_reference is often null on the create response and is not sent on collection callbacks. The provider ID for a collection arrives as collection.provider_transaction_id.

5. Send money

Payouts use the same shape, from the other direction. This endpoint requires your IP to be whitelisted and a disbursement subscription.

curl -X POST https://wallet.wearemarz.com/api/v1/send-money \
  -H 'Authorization: Basic YOUR_BASE64_CREDENTIALS' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 1000,
    "phone_number": "+256700000000",
    "country": "UG",
    "reference": "123e4567-e89b-12d3-a456-426614174001",
    "description": "Payout to customer",
    "callback_url": "https://your-app.com/webhooks/marzpay"
  }'

6. Check your work

Read the balance

GET /balance returns available, card, and total wallet balances plus daily, weekly, and monthly summaries.

Read a transaction

GET /transactions/{uuid} returns the same envelope as the callback, so one parser handles both.

Replay a callback

Point callback_url at a request bin while you build, then swap in your real endpoint.

Verify signatures

Enable webhook signing and compare X-MarzPay-Signature before you trust a payload.

Common first-run errors

Error code	What it means	Fix
`UNAUTHENTICATED` / `401`	The Basic header is missing, malformed, or the secret was rotated	Re-encode `key:secret` and redeploy
`VALIDATION_ERROR`	A required field is missing or badly typed	Read `errors` for the field list
`DUPLICATE_REFERENCE`	That UUID was already used for a collection	Generate a new UUID per attempt
`SERVICE_NOT_SUBSCRIBED`	No active subscription for that product and market	Subscribe in the marketplace
`INSUFFICIENT_BALANCE`	Wallet cannot cover amount plus charge	Top up, or send from the card wallet
`FORBIDDEN` / `403`	IP not whitelisted for a payout endpoint	Add the server IP in dashboard settings

Get started

Collections

Disbursements

Bills & airtime

Webhooks & platform

Build tools

Support

1. Create your account

2. Generate API credentials

3. Know your base URL

4. Collect money

5. Send money

6. Check your work

Read the balance

Read a transaction

Replay a callback

Verify signatures

Common first-run errors

​1. Create your account

​2. Generate API credentials

​3. Know your base URL

​4. Collect money

​5. Send money

​6. Check your work

Read the balance

Read a transaction

Replay a callback

Verify signatures

​Common first-run errors

1. Create your account

2. Generate API credentials

3. Know your base URL

4. Collect money

5. Send money

6. Check your work

Common first-run errors