Morzepay API

Collect mobile money, send payouts and give each of your own customers a wallet with its own balance. Every request is made from your server with an API key.

Base URL:

Requests and responses are JSON. Successful responses look like {"success": true, "data": {...}}. Supported networks today: MTN and Airtel Uganda, in UGX.

How wallets fit together

Your business has one or more main wallets. Under each main wallet you can create sub-wallets, one per customer on your platform (a shop on your POS, a member of your app). Each wallet has its own balance and transaction history. Money moves into a wallet through collections or transfers, and out through payouts or transfers.

Authentication

Create API keys in the dashboard under Developers. Send the key in the Authorization header. Keys are shown once; store them in your server's environment, never in a browser or mobile app.

Authorization: Bearer mp_live_3f9a1c0b2e7d_9b1c...

Keys created before the rename start with tp_ instead of mp_; they keep working, so there is nothing to change.

Every key belongs to one business and is limited in three ways:

Sandbox and live

Every account has two separate environments. Test keys (mp_test_…) only see test wallets and never touch real money. Live keys (mp_live_…) only see live wallets and are available after your business is verified. Wallet, transaction and reference namespaces are fully separate, so the same reference can exist in both.

Every object includes livemode (true or false), including webhook payloads.

Test phone numbers

The 5-requests-per-number-per-10-minutes rule applies in the sandbox too, so you can test your handling of MSISDN_RATE_LIMITED. Test traffic never counts against live limits.

Going live

Verify your business under Go live in the dashboard. Live payouts are limited per rolling 7 days according to your account type; the remaining allowance is returned by Quote fees as weekly_limit_remaining.

Amounts and fees

Send amounts as whole UGX integers: 5000, not "5000" or 5000.5. Mobile money transactions must be between 500 and 5,000,000 UGX. Responses return money as decimal strings, such as "1136.88", because network fees can include fractions.

Collection fees

Collections cost 3.5% of the amount the customer pays, all-in. Each wallet decides who pays it with deposit_fee_bearer, and you can override it per request with fee_bearer:

Payout fees

Transfer fees

Each wallet-to-wallet transfer costs a flat UGX 200, paid by the sending wallet on top of the amount. Any fee you add yourself (see Transfers) is extra and goes to your own fee wallet.

Payout fees

Payout fees are a flat amount per band, starting at UGX 800. Before sending, Morzepay holds the payout amount plus an estimated fee with a safety buffer. If the wallet can't cover that, the payout is refused with 402 INSUFFICIENT_FUNDS and nothing is sent. When the payout completes, any unused part of the estimate goes back to the wallet. Use Quote fees to show the numbers before you send.

Errors

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_FUNDS",
    "message": "The wallet cannot cover the payout plus the estimated mobile money fee.",
    "details": { "available": "3000.00", "required": "5800.00", "amount": "5000.00", "estimated_fee": "800.00" }
  },
  "request_id": "req_6f1d0c2b9a8e7d6c5b4a"
}

Idempotency

Network problems happen. To retry a POST safely, send an Idempotency-Key header (8–80 letters, digits, - or _). Retrying with the same key and body returns the original response with an Idempotent-Replayed: true header, and never moves money twice. Reusing a key with a different body returns 422 IDEMPOTENCY_MISMATCH. Keys are kept for 24 hours.

Money-moving calls also require your own unique reference (8–36 characters). A second request with the same reference returns 409 DUPLICATE_REFERENCE.

Rate limits

Each key can make 120 requests per minute. Separately, the mobile networks allow at most 5 payment requests per phone number every 10 minutes. A sixth request returns 429 MSISDN_RATE_LIMITED with retry_after_seconds, so show your customer when they can try again rather than retrying in a loop.

List wallets

Permission wallets:read. Optional query parameters: external_ref (find the wallet for one of your customers), parent_wallet_id, limit (1–100, default 50), starting_after (a wallet id, for paging).

curl "https://morzepay.com/v1/wallets?external_ref=shop-0192" \
  -H "Authorization: Bearer $MORZEPAY_KEY"

Create a sub-wallet

Permission wallets:write. Main wallets are created in the dashboard; the API creates sub-wallets under them.

curl "https://morzepay.com/v1/wallets" -X POST \
  -H "Authorization: Bearer $MORZEPAY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: create-shop-0192" \
  -d '{
    "parent_wallet_id": "wal_8fK2mQx7RtP4nVb9LcHs2w",
    "name": "Nakasero Pharmacy",
    "external_ref": "shop-0192",
    "deposit_fee_bearer": "customer"
  }'

Response 201

{
  "success": true,
  "data": {
    "id": "wal_Zq4Hn8YtV2kPm6RbX3cLw9",
    "kind": "sub",
    "parent_wallet_id": "wal_8fK2mQx7RtP4nVb9LcHs2w",
    "name": "Nakasero Pharmacy",
    "external_ref": "shop-0192",
    "currency": "UGX",
    "balance": "0.00",
    "deposit_fee_bearer": "customer",
    "status": "active",
    "created_at": "2026-10-04T14:20:11+03:00"
  }
}

Wallet balance

Permission wallets:read. The wallet id is required: a key never sees a combined balance it isn't allowed to.

curl "https://morzepay.com/v1/wallets/wal_Zq4Hn8YtV2kPm6RbX3cLw9" \
  -H "Authorization: Bearer $MORZEPAY_KEY"

Response 200

{ "success": true, "data": { "id": "wal_Zq4Hn8YtV2kPm6RbX3cLw9", "balance": "48500.00", "currency": "UGX", "status": "active", ... } }

Wallet transactions

Permission transactions:read. Newest first. Query: limit (1–100, default 25) and starting_after (a transaction id) to page backwards. The response has items and has_more.

Quote fees

Permission wallets:read. Shows what a collection, payout or transfer will cost before you make it. Nothing is created. type is deposit, payout or transfer; for transfers you can include your own fee to see the total.

curl "https://morzepay.com/v1/quotes" -X POST \
  -H "Authorization: Bearer $MORZEPAY_KEY" -H "Content-Type: application/json" \
  -d '{ "type": "payout", "wallet_id": "wal_Zq4Hn8YtV2kPm6RbX3cLw9", "amount": 20000, "msisdn": "+256771234567" }'

{ "success": true, "data": {
  "type": "payout", "amount": "20000.00", "estimated_fees": "1100.00",
  "amount_held": "21100.00", "wallet_balance": "48500.00", "sufficient_funds": true } }

Collect a payment

Permission deposits:write. Sends a payment prompt to the customer's phone. The wallet is credited only after the customer approves and the network confirms.

curl "https://morzepay.com/v1/deposits" -X POST \
  -H "Authorization: Bearer $MORZEPAY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-77812" \
  -d '{
    "wallet_id": "wal_Zq4Hn8YtV2kPm6RbX3cLw9",
    "msisdn": "+256771234567",
    "amount": 10000,
    "reference": "order-77812",
    "fee_bearer": "customer",
    "description": "Order 77812",
    "metadata": { "order_id": "77812" }
  }'

Response 201

{
  "success": true,
  "data": {
    "id": "txn_Rk3Lp9WmQ2vX7bN4cTz8Hd",
    "type": "deposit",
    "status": "processing",
    "wallet_id": "wal_Zq4Hn8YtV2kPm6RbX3cLw9",
    "amount": "10000.00",
    "customer_charged": "10363.00",
    "fee_bearer": "customer",
    "net": null,
    "msisdn": "+256771234567",
    "provider": "MTN_UGANDA",
    "fee": null,
    "fee_estimated": "363.00",
    "reference": "order-77812",
    ...
  }
}

Status lifecycle

processing means the prompt is on the customer's phone. Wait for the deposit.succeeded or deposit.failed webhook, or poll Get a transaction. A rare review status means the network reported something unexpected (for example, a different amount) and our team is checking it; no money is credited until it's resolved.

Send a payout

Permission payouts:write and an IP allowlist on the key. Same fields as a collection, except fee_bearer. The wallet pays the network fee.

curl "https://morzepay.com/v1/payouts" -X POST \
  -H "Authorization: Bearer $MORZEPAY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: withdraw-5521" \
  -d '{
    "wallet_id": "wal_Zq4Hn8YtV2kPm6RbX3cLw9",
    "msisdn": "+256701234567",
    "amount": 20000,
    "reference": "withdraw-5521",
    "description": "Shop withdrawal"
  }'

The response includes amount_held, the amount plus the fee estimate taken from the wallet immediately. On payout.succeeded, fees.provider holds the real fee and net the final change to the wallet. On payout.failed, the full hold returns to the wallet.

Transfer between wallets

Permission transfers:write. Instant, with a flat UGX 200 transfer fee paid by the sender. Both wallets must belong to your business and be visible to the key.

Example: a peer-to-peer app charging 1% (UGX 500 on 50,000), collected into its main wallet:

curl "https://morzepay.com/v1/transfers" -X POST \
  -H "Authorization: Bearer $MORZEPAY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: p2p-90311" \
  -d '{
    "from_wallet_id": "wal_Zq4Hn8YtV2kPm6RbX3cLw9",
    "to_wallet_id": "wal_Pt7Kc2NxW9mQ4vR8bLd3Hy",
    "amount": 50000,
    "fee": 500,
    "reference": "p2p-90311",
    "description": "Send 50k to John"
  }'

The response is the sender's transfer_out transaction with status: "success". The receiver gets a matching transfer_in, and the fee wallet a fee_in.

Verify a phone number

Permission msisdn:validate. Returns the registered name so your customer can confirm who they're paying. MTN and Airtel Uganda only. Limited to 30 checks per minute per key.

curl "https://morzepay.com/v1/msisdn/validate" -X POST \
  -H "Authorization: Bearer $MORZEPAY_KEY" -H "Content-Type: application/json" \
  -d '{ "msisdn": "0771234567" }'

{ "success": true, "data": { "msisdn": "+256771234567", "valid": true, "customer_name": "JOHN DOE", "provider": "MTN_UGANDA", "message": null } }

Get a transaction

Permission transactions:read. Use it to poll if you can't receive webhooks; every 10–30 seconds is plenty.

Fee fields: fee_estimated is known when the transaction is created; fee is the final fee once it succeeds (for collections it's always the advertised 3.5%). For transfers, fee is the UGX 200 transfer fee and merchant_fee is any fee you added.

Create an invoice

Permission invoices:write. Invoices work like Stripe's: you create a draft, finalize it (which gives it a number and freezes it), and your customer pays it on a hosted page with MTN Mobile Money or Airtel Money. We email them a PDF copy and a receipt when they pay.

curl "https://morzepay.com/v1/invoices" -X POST \
  -H "Authorization: Bearer $MORZEPAY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: inv-order-1001" \
  -d '{
    "customer": { "name": "Sarah Namuli", "email": "[email protected]", "phone": "0772418905" },
    "items": [
      { "description": "Website design (5 pages)", "quantity": 1, "unit_amount": 450000 },
      { "description": "Hosting, 12 months", "quantity": 2, "unit_amount": 75000 }
    ],
    "tax_percent": 18,
    "days_until_due": 14,
    "reference": "order-1001",
    "send": true
  }'

Response 201

{
  "success": true,
  "data": {
    "id": "inv_UfwyBh1W4Jfa6iG2u2AVT3",
    "object": "invoice",
    "number": "NILE-0001",
    "status": "open",
    "customer": { "name": "Sarah Namuli", "email": "[email protected]", "phone": "+256772418905", "address": null },
    "lines": [ { "description": "Website design (5 pages)", "quantity": 1, "unit_amount": "450000.00", "amount": "450000.00" }, ... ],
    "subtotal": "600000.00", "tax_percent": 18, "tax": "108000.00", "total": "708000.00",
    "amount_paid": "0.00", "amount_due": "708000.00",
    "due_date": "2026-11-11",
    "hosted_invoice_url": "https://morzepay.com/i/3f31d270b9829c826d28f0a4e68d7715",
    "invoice_pdf": "https://morzepay.com/i/3f31d270b9829c826d28f0a4e68d7715/pdf",
    "receipt_url": null,
    "delivery": { "email": true, "sms": null }
  }
}

hosted_invoice_url is the payment link: share it anywhere (WhatsApp, SMS, your app). invoice_pdf downloads the PDF without an API key, so you can attach or link it.

Invoice lifecycle

past_due is true for open invoices after their due date. To change a finalized invoice, void it and create a new one, like Stripe.

Finalize, send, void

Update a draft. Send only the fields you want to change. On finalized invoices only metadata can change.

Assigns the next number and opens it for payment. Totals must be between UGX 500 and UGX 5,000,000 (the mobile money limits).

Body { "via": ["email", "sms"] }. Emails the PDF with a pay button, and/or texts the payment link. Finalizes drafts first.

Records money you received outside Morzepay (cash, bank): { "paid_out_of_band": true, "note": "Cash at the shop", "email_receipt": true }. The invoice becomes paid and a receipt is issued. Your wallet balance doesn't change.

Deletes a draft. Finalized invoices can't be deleted; void them instead.

List and retrieve invoices

Permission invoices:read. Filters: status, customer_email, reference. Paginate with starting_after (an invoice id). Newest first.

Includes payments: each attempt on the hosted page with its status, payer and transaction_id.

The invoice as a PDF (application/pdf).

Create a checkout session

Permission checkout:write. Like Stripe Checkout: create a session for an order, redirect your customer to its url, and we send them back to your success_url once they've paid. The page handles the phone prompt, waiting, retries and the receipt.

curl "https://morzepay.com/v1/checkout/sessions" -X POST \
  -H "Authorization: Bearer $MORZEPAY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-77812" \
  -d '{
    "title": "Order #77812",
    "line_items": [ { "description": "Rolex combo", "quantity": 2, "unit_amount": 7000 } ],
    "reference": "order-77812",
    "success_url": "https://yourshop.ug/thanks?session={CHECKOUT_SESSION_ID}",
    "cancel_url": "https://yourshop.ug/cart"
  }'

Response 201

{ "success": true, "data": { "id": "cs_J9WN4dg0YnY6VjMMwq0kL1", "object": "checkout.session", "status": "open",
  "url": "https://morzepay.com/c/83513594a9ee455aacf23ca24eeff21b", "amount_total": "14000.00", "reusable": false,
  "expires_at": "2026-10-29T09:00:23+03:00", ... } }

Don't trust the redirect alone to ship an order: confirm with the checkout.session.completed webhook or by retrieving the session.

Retrieve and expire checkout sessions

Permission checkout:read. Status is open, complete (paid; see transaction_id and receipt_url) or expired. Includes payments.

Stops a session or payment link from accepting payments.

Receipts

Every payment on an invoice or checkout page gets a numbered receipt, emailed to the payer when we have their address. Receipts are also available for any successful collection.

Permission transactions:read. The last one creates the receipt the first time you ask for it. Each receipt has a public url and pdf you can give your customer.

{ "success": true, "data": { "id": "rcpt_WDL1pxuSr3cCcrFL1im2Th", "object": "receipt", "number": "NILE-R0001",
  "amount_paid": "733679.00", "fee": "25679.00", "payment_method": "MTN Mobile Money",
  "invoice_number": "NILE-0001", "url": "https://morzepay.com/r/5c0e0f50...", "pdf": "https://morzepay.com/r/5c0e0f50.../pdf", ... } }

Webhooks

Set a notification URL in the dashboard under Developers. We POST JSON to it for these events:

Invoice and checkout payments also send the usual deposit.succeeded for the underlying transaction; its metadata holds the invoice_id or checkout_session_id.

POST /webhooks/morzepay
Morzepay-Event: deposit.succeeded
Morzepay-Delivery: evt_Mx8Qp3VnK7rT2bWc9LhZ4d
Morzepay-Signature: t=1791127650,v1=5e8f0c7a...

{
  "id": "evt_Mx8Qp3VnK7rT2bWc9LhZ4d",
  "event": "deposit.succeeded",
  "created_at": "2026-10-04T14:07:51+03:00",
  "data": { "id": "txn_Rk3Lp9WmQ2vX7bN4cTz8Hd", "status": "success", "net": "10000.00", ... }
}

Events are sent immediately after the transaction changes. Use Send test event under Developers in the dashboard to check your endpoint: it sends a ping event and shows exactly what your server answered.

Respond with any 2xx within 10 seconds. Otherwise we retry after 1 min, 5 min, 15 min, 1 h, 2 h, 6 h, 12 h and 24 h. The same event can arrive more than once, so store the event id and ignore repeats. Redirects are not followed, and URLs must be public https:// addresses.

Verifying signatures

Always verify the signature before trusting a webhook. Compute HMAC-SHA256 of t + "." + raw_body with your signing secret and compare it to v1 in constant time. Reject timestamps more than 5 minutes old.

<?php
$secret  = getenv('MORZEPAY_WEBHOOK_SECRET');           // whsec_...
$body    = file_get_contents('php://input');            // raw body, before json_decode
$header  = $_SERVER['HTTP_MORZEPAY_SIGNATURE'] ?? '';

parse_str(str_replace(',', '&', $header), $sig);           // ['t' => ..., 'v1' => ...]
$expected = hash_hmac('sha256', ($sig['t'] ?? '') . '.' . $body, $secret);

if (!hash_equals($expected, $sig['v1'] ?? '') || abs(time() - (int) ($sig['t'] ?? 0)) > 300) {
    http_response_code(400);
    exit;
}

$event = json_decode($body, true);
// Deduplicate on $event['id'], then update your order using $event['data']['reference'].
http_response_code(200);

Treat the webhook as a signal: for high-value actions, confirm with GET /v1/transactions/{id} before releasing goods.