Build payments into anything

Cashmora lets your website, app or system collect mobile money from MTN and Airtel customers in Uganda, send payouts to any MTN or Airtel number, and show a hosted checkout inside your own pages.

Every successful response is {"status":"success","data":{…}}. Lists add "meta". Errors are {"status":"error","error":{"code":"…","message":"…","fields":{…}}}.

Take a test payment in five minutes. No real money moves in sandbox.

1. Create a Cashmora account and verify your email.
2. Subscribe to Mobile Collections under Products (free in sandbox).
3. Create a test key under Developers → API keys. It starts with cm_test_sk_.
4. Request a payment from the test number 0770000001. It succeeds a few seconds later.
5. Add a webhook endpoint under Developers → Webhooks so your system hears about results without polling.

curl -X POST https://api.cashmora.co.ug/v1/collections \
  -H "Authorization: Bearer cm_test_sk_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id":"3f8e4c1a-6b2d-4f7e-9a10-5c3b2e1d0f9a","phone":"0770000001","amount":5000,"reference":"ORDER-1042"}'

When your business is verified and live, create a live key (cm_live_sk_) and change only the key on your server.

Send your secret key as a bearer token. Keys belong on your server only: never in a browser, a mobile app or a public repository. If a key leaks, revoke it under Developers → API keys; it stops working immediately.

• Allow payouts: a key can only send money if this was ticked when it was created. Use collection-only keys wherever you can.
• Allowed IPs: optionally lock a key to your servers' addresses.
• The key decides the mode of each call (sandbox or live). Nothing else changes.

curl https://api.cashmora.co.ug/v1/balance -H "Authorization: Bearer cm_test_sk_YOUR_KEY"

New businesses start in sandbox. After verification (KYC), Cashmora enables live payments. Your test keys keep working after go-live, so developers can keep building safely.

• Test keys → sandbox: the simulator answers instead of MTN/Airtel, using the test numbers.
• Live keys → real money.
• Webhook endpoints, balances and transactions are separate for each mode, so test events never reach your live system.

With a test key, these numbers force an outcome. Any other valid MTN or Airtel number succeeds after a few seconds.

077… numbers are MTN, 070… numbers are Airtel. Both networks work in sandbox even while a network is under maintenance for live money.

The checkout page works inside an iframe (no cookies needed), so it can sit in a modal or a section of your own checkout. It sends your window two kinds of messages:

<iframe id="cashmora" src="CHECKOUT_URL" style="width:100%;max-width:440px;border:0;height:420px"></iframe>
<script>
  window.addEventListener('message', function (e) {
    if (!e.data || e.data.source !== 'cashmora') return;
    var frame = document.getElementById('cashmora');
    if (e.data.type === 'resize') { frame.style.height = e.data.height + 'px'; return; }
    if (e.data.type === 'payment.successful') {
      // Show "thank you" now, but confirm on your server before delivering (see below).
      window.location = '/orders/' + e.data.merchant_reference + '/thanks';
    }
  });
</script>

Prefer a redirect? Send redirect_url and cancel_url and open the url as a normal page.

Payment links are created in the dashboard (Collect → Payment links). Your system can open one with details already filled in, in a new tab, an iframe or a modal.

<iframe src="https://app.cashmora.co.ug/pay/YOURLINK?embed=1&amount=25000&phone=0772123456&reference=INV-2041"
        style="width:100%;max-width:440px;border:0;height:460px"></iframe>

Links send the same resize and payment.* messages (with link instead of checkout). The customer can change pre-filled values, so check the amount in the webhook before delivering. For an amount that can't be changed, use a hosted checkout.

Add an HTTPS endpoint under Developers → Webhooks. We POST a signed JSON event when something final happens and retry for about 14 hours (1 min, 5 min, 30 min, 2 h, 12 h) until your endpoint answers with any 2xx. Answer quickly; do slow work afterwards.

POST /your/webhook/url
Content-Type: application/json
Cashmora-Event: collection.successful
Cashmora-Delivery: 01a1f3c2-7d0e-7b4a-9c1e-2f6a8b0d4e11
Cashmora-Signature: t=1792663200,v1=5f2b1c…e9

{
  "id": "01a1f3c2-7d0e-7b4a-9c1e-2f6a8b0d4e11",
  "created_at": "2026-10-23T09:15:07Z",
  "type": "collection.successful",
  "data": { "id": "CM-COL-8F3K2Q9XAB", "object": "collection", "status": "successful", "amount": 5000, "reference": "ORDER-1042", "checkout": null }
}

• Events can arrive more than once: process each Cashmora-Delivery (or event id) only once.
• Events can arrive out of order: trust the status inside, or fetch the transaction.

Every event is signed with your endpoint's secret (Webhooks → Reveal secret). Compute HMAC-SHA256 of <t>.<raw body> with the secret and compare it with v1 in constant time. Reject events older than 5 minutes. Always use the raw request body, not re-encoded JSON.

<?php
$secret = getenv('CASHMORA_WEBHOOK_SECRET');
$body   = file_get_contents('php://input');
preg_match('/t=(\d+),v1=([a-f0-9]+)/', $_SERVER['HTTP_CASHMORA_SIGNATURE'] ?? '', $m);
$expected = hash_hmac('sha256', ($m[1] ?? '') . '.' . $body, $secret);
if (!$m || !hash_equals($expected, $m[2]) || abs(time() - (int) $m[1]) > 300) {
    http_response_code(400);
    exit('Invalid signature');
}
$event = json_decode($body, true);
if ($event['type'] === 'collection.successful') {
    // mark order $event['data']['reference'] as paid, once
}
http_response_code(200);

// Express: the RAW body is required for this route
const crypto = require('crypto');
app.post('/webhooks/cashmora', express.raw({ type: 'application/json' }), (req, res) => {
  const [, t, v1] = (req.get('Cashmora-Signature') || '').match(/t=(\d+),v1=([a-f0-9]+)/) || [];
  const expected = crypto.createHmac('sha256', process.env.CASHMORA_WEBHOOK_SECRET).update(`${t}.${req.body}`).digest('hex');
  const ok = v1 && v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected))
    && Math.abs(Date.now() / 1000 - Number(t)) <= 300;
  if (!ok) return res.status(400).send('Invalid signature');
  const event = JSON.parse(req.body);
  res.sendStatus(200);
});

import hmac, hashlib, os, re, time
from flask import request, abort

@app.post('/webhooks/cashmora')
def cashmora_webhook():
    body = request.get_data()
    m = re.match(r't=(\d+),v1=([a-f0-9]+)', request.headers.get('Cashmora-Signature', ''))
    if not m:
        abort(400)
    t, v1 = m.groups()
    expected = hmac.new(os.environ['CASHMORA_WEBHOOK_SECRET'].encode(), f'{t}.'.encode() + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, v1) or abs(time.time() - int(t)) > 300:
        abort(400)
    return '', 200

Send callback_url on a collection, payout or checkout and that transaction's final events are POSTed there too: same body, retries and Cashmora-Signature header as webhooks. They are signed with your callback_url signing secret (Webhooks → callback_url signing secret); test and live have different secrets. The URL must be public HTTPS; private and local addresses are refused. If every payment goes to the same place, use a webhook endpoint instead.

Every create request carries two different identifiers:

• Generate the request_id when you create the attempt, save it before calling us, and reuse it only to retry that attempt.
• Same request_id + same phone and amount → the original transaction (HTTP 200, header Idempotent-Replayed: true). Nobody is charged twice.
• Same request_id + different details → 409 duplicate_request_id.
• On a timeout or 5xx, retry with the same request_id, or look it up with GET /v1/collections?request_id=….

Part payments. One order can have several payments, each with its own request_id and the same reference:

POST /v1/collections  {"request_id":"9b1d…","reference":"OR-0097878","amount":140000}   → successful
POST /v1/collections  {"request_id":"4c7a…","reference":"OR-0097878","amount":60000}    → successful
GET  /v1/collections?reference=OR-0097878&status=successful                           → 200,000 in total

Each successful collection pays the Mobile Collections fee shown in your dashboard. You choose who pays it, per business (Products → Mobile Collections) or per request (fee_paid_by):

Payout fees are always added on top of the payout and taken from your balance (total).

• Business verified and live payments enabled by Cashmora.
• Two-step verification on for everyone who can create keys or send money.
• Live key in your server's environment settings, never in code. A separate key with "Allow payouts" only where needed, ideally IP-locked.
• Live webhook endpoint (HTTPS) added, signatures verified, events de-duplicated by Cashmora-Delivery.
• Goods released only on successful; unknown treated as "still waiting".
• A new request_id for every attempt, saved before the call; retries reuse it. Orders matched by reference.
• network_unavailable handled by showing its message (e.g. "Please use an MTN number").

These docs are available in machine-friendly formats, so coding assistants and crawlers can integrate Cashmora correctly:

Key rules for generated code: keep the secret key on the server; send a fresh request_id per attempt and reuse it on retries; deliver only on successful (or a verified collection.successful webhook); treat unknown as pending.