API Documentation

Choose Your Integration

Samsoftpay supports three integration shapes. Pick the row that matches what you're building — each links to the endpoints you need. They can be combined (a POS that both takes payments and pays out uses two of them).

How You Connect

The whole integration is two connections in opposite directions. Get these right and everything else follows.

POST https://api.samsoftpay.com/v1/charges
Authorization: Bearer sk_live_…        ← your API key (proves YOU to US)

POST https://www.yourdomain.com/webhooks/samsoftpay
X-Samsoftpay-Signature: …              ← verify with your whsec_ (proves US to YOU)

Two keys — don't mix them up

Quickstart

To integrate with Samsoftpay you need exactly two things:

1. Base URL: https://api.samsoftpay.com (same for test and live).
2. Your API key: sk_test_… from a free account (instant, no approval), sent as Authorization: Bearer <key>.

No IPN registration, no IP whitelisting, no token exchange. This first charge works in under a minute:

curl -X POST https://api.samsoftpay.com/v1/charges \
  -H "Authorization: Bearer sk_test_YOUR_TEST_KEY" \
  -H "Idempotency-Key: my-first-charge-001" \
  -H "X-Timestamp: $(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 5000,
    "currency": "UGX",
    "channel": "mtn_momo",
    "customer": {"phone": "256700000000"},
    "reference": "order-001"
  }'

Response:

{
  "id": "txn_9f2c41d8a3b7e615",
  "mode": "test",
  "status": "authorized",
  "amount": 5000,
  "fee": 200,
  "currency": "UGX",
  "channel": "mtn_momo",
  "reference": "order-001"
}

Poll GET /v1/charges/<id> until status is succeeded. The test number 256700000000 always succeeds (see Testing for numbers that fail on demand). Prefer push? Add a webhook URL on your Account page and we deliver signed events instead. Webhooks are optional, and polling is fully supported.

Going live later is a one-line change: swap in your sk_live_ key. Nothing else changes.

Authentication

Samsoftpay uses Bearer token authentication. Pass your Secret Key in the Authorization header on every request.

Kiosk-safe keys: for code that ships on a public device (a vending machine, a kiosk app), use a collections-only key (sk_test_col_… / sk_live_col_…, generated on your Account page). It can create charges, orders and payment links but is refused with 403 on payouts and refunds, so a key pulled off a device can never move money out. Never embed your full secret key on a device.

import requests

headers = {
    "Authorization": "Bearer sk_test_YOUR_TEST_KEY",
    "Content-Type": "application/json",
}

const headers = {
  "Authorization": "Bearer sk_test_YOUR_TEST_KEY",
  "Content-Type": "application/json",
};

curl -H "Authorization: Bearer sk_test_YOUR_TEST_KEY" \
     https://samsoftpay.com/v1/charges

Required Headers

All POST requests require these additional headers:

import time, uuid

headers = {
    "Authorization": "Bearer sk_test_YOUR_TEST_KEY",
    "Idempotency-Key": str(uuid.uuid4()),
    "X-Timestamp": str(int(time.time())),
    "Content-Type": "application/json",
}

Idempotency semantics

Keys are reserved before execution: two concurrent requests with the same key can never both run; the loser gets 409 and should retry shortly. Replaying a key returns the original response, unchanged, plus the header Idempotent-Replayed: true so you can tell a replay from a fresh execution. Keys are retained for 30 days. On a network error, timeout or 5xx, retry with the same key. That is the whole point. Idempotency-Key is required on the money POSTs and optional-but-honored on payment links and vending orders.

Charges

Collect money from a customer via mobile money or card.

Create a Charge

import requests, time, uuid

resp = requests.post(
    "https://samsoftpay.com/v1/charges",
    headers={
        "Authorization": "Bearer sk_test_YOUR_TEST_KEY",
        "Idempotency-Key": str(uuid.uuid4()),
        "X-Timestamp": str(int(time.time())),
        "Content-Type": "application/json",
    },
    json={
        "amount": 10000,
        "currency": "UGX",
        "channel": "mtn_momo",
        "customer": {"phone": "256700123456"},
        "reference": "order-001",
    }
)
print(resp.json())
# {"id": "txn_abc123", "status": "authorized", "amount": 10000, "fee": 200, ...}

const resp = await fetch("https://samsoftpay.com/v1/charges", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_YOUR_TEST_KEY",
    "Idempotency-Key": crypto.randomUUID(),
    "X-Timestamp": String(Math.floor(Date.now() / 1000)),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 10000,
    currency: "UGX",
    channel: "mtn_momo",
    customer: { phone: "256700123456" },
    reference: "order-001",
  }),
});
const data = await resp.json();
console.log(data); // {id: "txn_abc123", status: "authorized", ...}

curl -X POST https://samsoftpay.com/v1/charges \
  -H "Authorization: Bearer sk_test_YOUR_TEST_KEY" \
  -H "Idempotency-Key: $(python3 -c 'import uuid; print(uuid.uuid4())')" \
  -H "X-Timestamp: $(date +%s)" \
  -H "Content-Type: application/json" \
  -d '{"amount":10000,"currency":"UGX","channel":"mtn_momo","customer":{"phone":"256700123456"}}'

Get a Charge

resp = requests.get(
    "https://samsoftpay.com/v1/charges/txn_abc123",
    headers={"Authorization": "Bearer sk_test_YOUR_TEST_KEY"}
)
# status: "pending" | "authorized" | "succeeded" | "failed"

Testing

With an sk_test_ key, MTN Mobile Money and Airtel Money never touch a real network. A charge settles a few seconds after you request it, using the phone number as the signal for what should happen. An ordinary phone number always succeeds. Use one of these to test a specific outcome on purpose:

Payout failure simulation

Payouts have their own deterministic scenarios, matched on the recipient number's last 9 digits. Rehearse your payout.failed handling before it can happen with real money. A failed payout refunds the amount and the fee to your available balance.

Funding your sandbox wallet

A payout or refund needs available balance (amount + fee) or it is rejected before a pout_ id is created — a fresh sandbox starts empty. Two ways to add test money (it lives on a separate test ledger, is never withdrawable, and disappears at production go-live):

• One click: Dashboard → Wallet → Add test funds. No KYC required to test — add as much as you need, instantly, then run payouts/refunds against it.
• Or take a sandbox payment: create a charge with an sk_test_ key using an ordinary test number — it settles in seconds and credits your sandbox available balance (minus the fee).

Check it any time with GET /v1/balance: available must be ≥ Σ amounts + Σ fees before payroll/bulk runs.

Exact charge.failed payloads

Each failure number produces a charge.failed webhook whose data carries the core charge fields (id, amount, fee, currency, channel, status, reference, failure_reason, completed_at) plus mode. Build your error handling against these exact payloads:

256700000001:

{
  "id": "txn_9f2c41d8a3b7e615",
  "amount": 5000,
  "fee": 200,
  "currency": "UGX",
  "channel": "mtn_momo",
  "status": "failed",
  "merchant_reference": "order-001",
  "failure_reason": "insufficient_funds",
  "completed_at": "2026-08-20T10:30:00+00:00"
}

256700000002: same shape with "failure_reason": "user_cancelled".

256700000003: same shape with "failure_reason": "timeout".

A successful charge's charge.succeeded data is identical in shape with "status": "succeeded" and "failure_reason": null.

Balance

What Samsoftpay is currently holding for you, per currency. Use this to reconcile your own records against ours. If you run a platform with its own user wallets, this is the figure your internal balances must add up to.

Retrieve your balance

resp = requests.get(
    "https://samsoftpay.com/v1/balance",
    headers={"Authorization": "Bearer sk_test_YOUR_TEST_KEY"}
)

# {
#   "mode": "live",
#   "balances": [
#     {"currency": "UGX", "available": 186250, "pending": 0, "cached": 186250, "total": 186250}
#   ],
#   "consistent": true,
#   "as_of": 1755900000
# }

Amounts are in minor units, like everywhere else in this API. Currencies are always reported separately and never summed together.

How your balance moves & how to reconcile

Your Samsoftpay balance is a real ledger we hold for you. It goes up when you collect and down when you pay out — every change is atomic and can never overdraft:

Keeping your app in sync (the reconciliation model):

• GET /v1/balance is the source of truth. If your app keeps its own mirror balance or per-user wallets, they must reconcile to this figure.
• Update on webhooks, verify with balance. Each state change fires a signed webhook — charge.succeeded raises your mirror, payout.succeeded/payout.failed adjusts it — so you don't have to poll. Treat webhooks as the nudge and GET /v1/balance (or GET /v1/charges / GET /v1/payouts) as the authority when they disagree.
• Deductions are real-time. The moment a payout is accepted, available drops by amount + fee; your app reads the new figure immediately.
• Fees & tax: the only Samsoftpay charge is the 1.5% fee (min UGX 200, cap UGX 5,000) on each charge and payout. The 0.5% Mobile-Money levy is deducted by MTN at the rail (not by us); URA VAT applies to fees. So reconcile against net (amount − fee), not gross.

Payouts

Send money out to a recipient's mobile money wallet. The merchant must have sufficient available balance.

Create a Payout

resp = requests.post(
    "https://samsoftpay.com/v1/payouts",
    headers={
        "Authorization": "Bearer sk_test_YOUR_TEST_KEY",
        "Idempotency-Key": str(uuid.uuid4()),
        "X-Timestamp": str(int(time.time())),
        "Content-Type": "application/json",
    },
    json={
        "amount": 50000,
        "currency": "UGX",
        "channel": "mtn_momo",
        "recipient": {"phone": "256780000001", "name": "Jane Doe"},
    }
)
print(resp.json())
# {"id": "pout_xyz789", "status": "authorized", "fee": 750, ...}

const resp = await fetch("https://samsoftpay.com/v1/payouts", {
  method: "POST",
  headers: {
    "Authorization": "Bearer sk_test_YOUR_TEST_KEY",
    "Idempotency-Key": crypto.randomUUID(),
    "X-Timestamp": String(Math.floor(Date.now() / 1000)),
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    amount: 50000,
    currency: "UGX",
    channel: "mtn_momo",
    recipient: { phone: "256780000001", name: "Jane Doe" },
  }),
});

Provider IDs & the "no id" case

An accepted payout returns a stable pout_… id immediately. It is immutable across pending → authorized → succeeded/failed, appears in every webhook (data.id), and is the key for GET /v1/payouts/{id}. A payout that reaches the rail keeps its id even when it later fails.

A request rejected before creation (bad request, wrong scope, or insufficient available balance) has no pout_… id and no record — read the error/failure_reason to see why, correct it and retry. A null id is a rejection, never a lost payout.

Payout status lifecycle

States never move backward. An ambiguous network error parks the payout authorized (never a false failed) and is resolved from MTN's own answer — poll GET /v1/payouts/{id} as the source of truth.

Machine-readable failure reasons

failure_reason is a stable code (with a human message where relevant): recipient_not_found, wallet_locked, timeout, insufficient_funds, user_cancelled, insufficient_balance (merchant wallet), rail_rejected.

Bulk payouts (payroll)

Up to 1000 items, per-item (not atomic — some items may succeed while others fail). Idempotency-Key is required; each item also dedupes on its reference. The array root may be payouts or items, and each item uses the same recipient:{phone,name} shape as the single endpoint.

POST /v1/payouts/bulk
{ "payouts": [
  { "amount": 50000, "recipient": { "phone": "256780000001", "name": "Emp One" }, "reference": "PR-001" },
  { "amount": 75000, "recipient": { "phone": "256780000002", "name": "Emp Two" }, "reference": "PR-002" }
] }

// -> per-item results, each correlatable by reference + provider id + status
{ "batch_id": "batch_…", "total": 2, "accepted": 2, "failed": 0, "results": [
  { "index": 0, "ok": true, "id": "pout_…", "status": "authorized", "reference": "PR-001" },
  { "index": 1, "ok": true, "id": "pout_…", "status": "authorized", "reference": "PR-002" }
] }

Payout webhooks

Configure a webhook URL on Account → Webhooks to receive payout.succeeded / payout.failed. Each event carries a stable evt_… id (dedupe on it), the pout_… id, your reference, status, amount, fee, currency and failure_reason — HMAC-signed exactly like charge events (see Verifying Webhooks).

Accept a Payment (Hosted Checkout)

The simplest way to take money — and the one most stores want. You create a payment link, send the customer to the returned url (or show its QR on a screen). They pick their method and pay on our secure page — you never handle a card number or a MoMo PIN, so you carry no PCI scope. This is the exact flow the WooCommerce plugin, the Shopify app, and TK's vending machines all use.

The flow (three steps)

1. POST /v1/payment-links              → { id, url, qr_png_url }
2. Send the customer to `url`           (redirect their browser, or show the QR)
     → they pick MTN / Airtel / card / crypto and pay on our page
3. Confirm the payment:  charge.succeeded webhook   OR   GET /v1/charges/<id>
     → then fulfil the order / dispense the product

resp = requests.post(
    "https://samsoftpay.com/v1/payment-links",
    headers={
        "Authorization": "Bearer sk_test_YOUR_TEST_KEY",
        "Content-Type": "application/json",
        "Idempotency-Key": str(uuid.uuid4()),
        "X-Timestamp": str(int(time.time())),
    },
    json={
        "amount": 25000,
        "reference": "order-1042",
        "description": "School Fees Payment",
        "success_url": "https://yourapp.com/thank-you",
        "cancel_url":  "https://yourapp.com/cart",
    },
)
data = resp.json()
# → send the browser here, or render the QR on a machine screen:
print(data["url"])          # https://samsoftpay.com/pay/lnk_…
print(data["qr_png_url"])   # a ready PNG of that same URL (no auth)

Where the customer returns

success_url and cancel_url are your return pages. After paying, the customer is offered a "Return to <you>" button to success_url; if you set neither, they stay on our hosted status page. Never trust the return redirect as proof of payment — always confirm server-side with the charge.succeeded webhook or GET /v1/charges/<id> (a customer can close the tab before returning).

The customer picks the channel — you don't

You never send a channel when creating a link. Our page shows the methods that are live (MTN Mobile Money today; Airtel Money and cards as they launch) and the customer chooses. Which method actually ran comes back on the charge's channel field.

Gift cards & vouchers work on this page

Because the customer pays on our hosted checkout, they can apply a gift-card / voucher code right there (a "Have a voucher?" field). This works for payment links, WooCommerce and Shopify — anything that lands on the hosted checkout. It does not apply to the raw POST /v1/charges API. See Gift Cards & Vouchers.

Checking the status

Poll GET /v1/charges/<id>, or wait for the webhook. The status field moves through:

Only release goods on succeeded. In the sandbox (sk_test_) a charge auto-completes with no real PIN or money — see Simulate or real?

Gift Cards & Vouchers

Gift cards are a merchant-issued store-credit. They are created and managed in your dashboard, and redeemed by the customer on the hosted checkout — there is deliberately no API endpoint to redeem one (a gift card is your own liability, not something an integrator's server should be able to spend).

How it works

• Issue: Dashboard → Gift Cards → create a card with a balance and currency. You get a code to hand to the customer.
• Redeem: on the hosted checkout (/pay/<id>), the customer enters the code in the "Have a voucher?" field. It's validated, then applied to the amount; the customer pays only the remainder (if any) by Mobile Money. A fully-covered order needs no rail payment at all.
• Where it works: anywhere the customer lands on our hosted checkout — payment links, WooCommerce, Shopify, vending. It does not apply to the direct POST /v1/charges API.

Gift cards are real, live store credit (there is no sandbox gift-card system) — a sandbox (sk_test_) checkout is refused a gift card by design.

Refunds

Returns money to the customer's mobile-money account via a disbursement. The customer is refunded the full original amount (a UGX 5,000 charge refunds UGX 5,000) — the platform gives its charge fee back to the merchant, so the merchant's net cost of a refund is only the payout fee, never the customer's money. Requires a full secret key and X-Timestamp. It is idempotent by design (no Idempotency-Key needed): a retry of an already-refunded charge returns 400 already_refunded.

HTTP 202
{
  "charge_id": "txn_...",
  "status": "refunded",
  "refund": { "id": "pout_...", "amount": 5000, "status": "authorized" }
}

The 202 means the refund was initiated, not yet paid. Like any payout, the customer's money-out lands on the rail moments later — treat refund.status as a payout status and confirm it reaches succeeded (poll GET /v1/payouts/<id> or watch the payout.succeeded / payout.failed webhook), not as final on the 202.

Refunding twice returns 400 {"error": "already_refunded"}. A charge that was created with a split cannot be refunded through this endpoint yet. You will receive 400 {"error": "split_charge_refunds_not_yet_supported"}; contact support to reverse a split charge.

Listing & Search

Newest first, cursor pagination. Use this to reconcile after a missed webhook. You never need to have stored an id to find a payment again.

GET /v1/charges?limit=20&status=succeeded&created_after=2026-08-01T00:00:00Z

{
  "object": "list",
  "data": [ { ...same shape as GET /v1/charges/<id>... } ],
  "has_more": true,
  "next_cursor": "txn_9f2c41d8a3b7e615"   // pass as ?starting_after=
}

Filters: status, reference (charges only), phone, email (reconcile by customer), created_after / created_before (ISO 8601), limit (1–100). phone matches on the last 9 digits, so 0780…, 256780… and +256 780… all find the same customer. Lists are scoped to your key's mode: a test key only ever sees test data. Failed charges carry failure_reason (e.g. insufficient_funds) on every charge object.

Subaccounts & Split Payments

For platforms settling money to multiple sub-merchants (vending operators, marketplace sellers, wallet users): register subaccounts, then split any charge.

{ "name": "Shop A", "payout_phone": "256772123456", "external_ref": "your-id-42" }
-> 201 { "id": "sub_...", "name": "Shop A", "status": "active" }

Then add split to a charge. Shares are fixed amounts or basis points of the net (amount minus our fee). Whatever the shares don't consume stays with you (the platform):

POST /v1/charges
{
  "amount": 100000, "channel": "mtn_momo",
  "customer": {"phone": "256700000000"},
  "split": [
    {"subaccount": "sub_a", "amount": 30000},
    {"subaccount": "sub_b", "bps": 2000}
  ]
}

Each share settles into its subaccount's own balance after the standard hold. See it on GET /v1/charges/<id> (a split array) and GET /v1/subaccounts/<id> (per-currency balances). An over-allocated split (shares exceeding the net) is rejected with 400 and nothing is created.

Vending Machines

Take Mobile Money on an unattended machine. You create an order, the machine shows the QR we return, the customer scans and pays on their phone, and we tell the machine to release the product the moment the payment succeeds. Your machine software never handles money.

Enable it first: Dashboard → Vending. While it is off, no order can be created and no machine will be told to dispense.

{
  "jqbh": "txyz00123",
  "shbh": "001",
  "paytype": "forwardPayCode",
  "status": "1",
  "ddbh": "lnk_3cc4668c388f4f00",
  "dsfjybh": "txn_...",
  "zfzh": "256783647260",
  "payAmount": 2500,
  "tkje": 0,
  "timestamp": 1789012345678,
  "splist": [
    {"spbh": "0001", "spmc": "Coca-Cola 500ml", "chsl": "1"}
  ],
  "sign": "<computed>"
}

resp = requests.post(
    "https://samsoftpay.com/v1/vending/orders",
    headers={
        "Authorization": "Bearer sk_test_YOUR_TEST_KEY",
        "Idempotency-Key": str(uuid.uuid4()),
        "X-Timestamp": str(int(time.time())),
        "Content-Type": "application/json",
    },
    json={
        "machine": "XY000123",
        "amount": 2500,
        "goods": [{"spbh": "0001", "spmc": "Coca-Cola 500ml", "spdj": 2500}],
    }
)
order = resp.json()
order["display_url"]  # open this on the machine screen — it shows the QR and
                      # switches itself to "collect your item" when done
order["qr_png_url"]   # or draw the QR yourself from order["qr_content"]

Poll an order if you would rather drive the screen yourself. Returns payment_status (unpaid, pending, succeeded, failed) and vending_status (pending, dispensing, dispensed, failed).

Retry a dispense that failed, for example because the machine was offline when the payment landed. The customer's money is never at risk: a retry only works on an order whose charge actually succeeded, and an order can never dispense twice.

Your machines, and the live tray contents and prices of one machine. Build your on-screen menu from this rather than hard-coding slots.

Per-machine money and dispense tally — reconcile what your cloud recorded for each machine against what Samsoftpay actually captured. This is the vending counterpart of GET /v1/balance: same source of truth (the order's transaction, never a cache), so it always agrees with the webhook feed you already received.

# every machine in your registry, with zero-order machines included
curl -H "Authorization: Bearer sk_live_.." \
     https://api.samsoftpay.com/v1/vending/machines/tallies

# one machine / a date window, for a nightly reconcile job
curl -H "Authorization: Bearer sk_live_.." \
     "https://api.samsoftpay.com/v1/vending/machines/tallies?machine=1707600112&since=2026-09-01T00:00:00Z"

=> {
  "mode": "live",
  "as_of": 1755900000,
  "machines": [{
    "machine": "1707600112", "name": "Kampala lobby", "registered": true,
    "orders": 120, "paid": 118,
    "collected": 2950000,      # sum of customer charges on paid orders
    "fees": 23600,             # processing fees, minor units
    "settled": 2900000,        # already swept out of the 24h hold
    "pending_hold": 50000,     # still inside its hold window
    "refunded": 0,             # money later returned to a customer
    "dispensed": 117, "dispense_failed": 1, "cancelled": 2
  }]
}

All money fields are in minor units, mode-scoped exactly like the rest of the API: a sandbox key sees only sandbox orders (never reconcile test money against live floats). Registered machines always appear — even with zero orders — so your machine list lines up with ours 1:1. Note this is a report: settlement itself stays per-merchant, not per-machine.

Webhook Events

Samsoftpay POSTs a JSON payload to your webhook_url whenever a charge or payout changes state. We retry up to 8 times with exponential backoff.

Respond with any 2xx status code within 5 seconds to acknowledge receipt.

The Envelope

Every delivery is one JSON envelope, sent as canonical JSON with no spaces (the signature covers these exact bytes). Shown pretty-printed here for readability:

{
  "id": "evt_1a2b3c4d5e6f7a8b9c0d1e2f",
  "timestamp": 1755900000,
  "event": "charge.succeeded",
  "data": {
    "id": "txn_abc123",
    "amount": 10000,
    "fee": 200,
    "currency": "UGX",
    "channel": "mtn_momo",
    "status": "succeeded",
    "merchant_reference": "order-001",
    "failure_reason": null,
    "completed_at": "2026-08-20T10:30:00+00:00"
  }
}

The envelope id is unique per event and retries share it, so dedupe on it. timestamp is Unix seconds; use it to enforce a replay window.

Event catalogue: charge.succeeded, charge.failed, payout.succeeded, payout.failed, vending.dispensed, vending.dispense_failed, dispute.opened (a customer used the public "Report a problem" link on a receipt. Respond within 72 hours; it never moves money by itself, and its details/contact fields are raw customer input: escape them before rendering), test.ping (the Account → Webhooks test button).

Verifying Webhooks

Every request includes an X-Samsoftpay-Signature header: an HMAC-SHA256 of the raw request body, signed with your webhook signing secret (whsec_…), shown in Account → Webhooks. It is unique to your account. Always verify before processing.

import hmac, hashlib
from flask import request, abort

WEBHOOK_SECRET = "your_webhook_signing_secret"

@app.post("/webhooks/samsoftpay")
def handle_webhook():
    sig = request.headers.get("X-Samsoftpay-Signature", "")
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, sig):
        abort(400, "invalid signature")

    event = request.get_json()
    if event["event"] == "charge.succeeded":
        order_id = event["data"]["merchant_reference"]
        # mark order as paid in your database
        pass

    return {"ok": True}

const crypto = require("crypto");

app.post("/webhooks/samsoftpay", express.raw({ type: "application/json" }), (req, res) => {
  const sig = req.headers["x-samsoftpay-signature"];
  const expected = crypto
    .createHmac("sha256", process.env.WEBHOOK_SECRET)
    .update(req.body)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig))) {
    return res.status(400).send("invalid signature");
  }

  const event = JSON.parse(req.body);
  if (event.event === "charge.succeeded") {
    // mark order as paid
  }
  res.json({ ok: true });
});

Webhook Operations & Retries

Respond with any 2xx within 5 seconds. Return 200 immediately and process asynchronously. A slow handler is indistinguishable from a dead one and will be retried. Retries carry the same envelope id, so dedupe on it, not on receipt count.

Retry schedule

The first attempt fires immediately. Each failure schedules the next attempt after a growing backoff, up to 8 attempts in total:

So a delivery keeps retrying for roughly two days after the event before giving up. After that, resend it yourself (below) or reconcile by listing charges.

Inspect & resend deliveries

Lists your most recent webhook deliveries, each with its event id (evt_…), event, status, attempts and last_response_code, so you can see exactly what we sent and how your endpoint answered.

Re-queues one delivery by its evt_… id and returns 202. The resent delivery carries the same envelope (same id), so your dedupe logic handles it like any retry.

Pre-flight a payout destination

MTN's own answer about a wallet before any money is earmarked. Returns msisdn, active and registered_name. Treat active: false as the hard stop; the name is the double-check (it can be null while our MTN KYC scope is pending). Sandbox is deterministic: 256700000001 resolves inactive, every other number is an active SANDBOX HOLDER. Full-scope keys only: a kiosk credential must not be able to enumerate wallet owners.

Egress IPs (only if your endpoint is IP-firewalled)

Verify the signature, don't rely on IP. The reliable way to trust a webhook is the X-Samsoftpay-Signature HMAC (see Verifying Webhooks) — it proves the request is really from us and can't be spoofed. That is all most integrators need.

Only if your webhook endpoint sits behind an IP allowlist do you need our outbound ranges. These are the source addresses our servers send from — they are not websites, so you can't open them in a browser. They can change if we move hosting region, so always keep signature verification as your primary check; treat the allowlist as a convenience, not the security boundary. Current outbound ranges:

Integration Best Practices

Error Catalog

Every error the API returns is JSON with a single error field, listed here verbatim (dynamic parts shown as …). The Retry? column is the contract: yes, same key means retry with the same Idempotency-Key; no, fix request means change something first; no, permanent means retrying will never help.

# Error response shape
{"error": "insufficient available balance: have 5000, need 50750 (amount 50000 + fee 750)"}

Authentication & headers

Idempotency & rate limits

Charges

Payouts & refunds

Vending

Asynchronous failures (not HTTP errors)

A charge or payout that is accepted (HTTP 201) can still fail later on the rail. That outcome arrives as "status": "failed" with a failure_reason, via webhook (charge.failed / payout.failed) or polling. Reproduce each one deterministically in the sandbox with a magic number (see Testing):

A failed payout refunds the amount and the fee to your available balance. A 404 anywhere means the resource does not exist, belongs to another merchant, or belongs to the other mode (test vs live) than your key.

Go-Live Checklist

The path from first sandbox charge to real money, in order. Every step is checkable. Do not skip the config-drift checks: they catch the classic "worked in test, silently broken in live" failures.

1. Build in the sandbox. Integrate with your sk_test_ key. Sandbox money lives on a separate ledger. Nothing you do here can touch real balances.
2. Test failure paths in both directions with the magic numbers. Charges: customer phones 256700000001/2/3 fail with insufficient_funds / user_cancelled / timeout. Payouts: the same numbers as the recipient fail with recipient_not_found / wallet_locked / timeout. Confirm your handlers for charge.failed and payout.failed, your webhook signature verification, and your dedupe on the envelope id.
3. Verify your business (KYC) on the dashboard. Live charges and payouts are refused with 400 until your account is verified. Test keys keep working throughout.
4. Config-drift checks before switching keys:
   • Live webhook URL set and verified. Use the Send test event button on Account → Webhooks, which POSTs a signed test.ping event to your endpoint; confirm your handler verifies the signature and returns 2xx.
   • Live key issued and stored server-side only (an environment variable, never in client code, mobile apps or repos).
   • Kiosk and vending devices carry sk_live_col_ collections-only keys, never full keys. A key pulled off a device must not be able to move money out.
5. First live charge, small amount. Verify it via GET /v1/charges/<id> and confirm the charge.succeeded webhook arrived and verified. Both paths must work before volume.
6. First live settlement confirmed on GET /v1/settlements. After the 24h hold (hourly sweep), the release appears as a settlement record and your available balance on GET /v1/balance moves. Now you know money in, money held and money withdrawable all agree.
7. Subscribe to the changelog. API changes land there first; response shapes are additive-only and webhook events are only ever added, so reading it is routine maintenance.