API basics

Every product in MarzPay runs on one REST API. Once you can authenticate and parse the money envelope, the rest of the endpoints follow the same pattern.

Property	Value
Base URL	`https://wallet.wearemarz.com/api/v1`
Version	`v1`, prefixed in the path
Auth	HTTP Basic, `base64(api_key:api_secret)`
Content types	`application/json`, and `multipart/form-data` on money movement
API reference	All endpoints

Authentication

Authorization: Basic YOUR_BASE64_CREDENTIALS

Build the value from your API key and secret, joined by a colon:

printf '%s' "$MARZPAY_KEY:$MARZPAY_SECRET" | base64

Node.js
PHP
Python
Go

const auth = Buffer.from(`${key}:${secret}`).toString("base64");
const headers = { Authorization: `Basic ${auth}` };

$auth = base64_encode($key . ':' . $secret);
$headers = ['Authorization' => 'Basic ' . $auth];

import base64
auth = base64.b64encode(f"{key}:{secret}".encode()).decode()
headers = {"Authorization": f"Basic {auth}"}

auth := base64.StdEncoding.EncodeToString([]byte(key + ":" + secret))
req.Header.Set("Authorization", "Basic "+auth)

A 401 almost always means the base64 value is stale, was double encoded, or contains a trailing newline. Recompute it in the same environment that sends the request.

Request conventions

string

required

Market code: UG, KE, RW, CD, ZM, CM, BJ, CI, GA, CG, SN, or SL. This decides the wallet and the payout rail. Congo-Brazzaville is CG, the DRC is CD.

string

Optional everywhere except the DRC, where you must send CDF (default) or USD. For every other market the currency follows the country: UGX, KES, RWF, ZMW, XAF, XOF, SLE.

string

required

A UUID v4 that you generate, unique per business across all API transactions, maximum 50 characters. Reuse returns DUPLICATE_REFERENCE. This is the key we echo on callbacks, so treat it as your idempotency key.

string

E.164 with the country code, for example +256700000000 or +254710000000. Required for mobile money, omitted for card collections.

number

Major currency units, not cents. 1000 is UGX 1,000. Uganda collections accept 500 to 10,000,000.

array

Up to 10 objects, each with one field and value, plus optional isPII: true. Echoed on the create response and at the top level of callbacks.

string

Per-transaction webhook target, maximum 255 characters, must be https. Final statuses only, both success and failure.

The money envelope

Every amount in a response is an object, never a bare number:

{
  "amount": { "formatted": "1,000.00", "raw": 1000, "currency": "UGX" },
  "charge": { "formatted": "35.00", "raw": 35, "currency": "UGX" },
  "net_amount": { "formatted": "965.00", "raw": 965, "currency": "UGX" }
}

amount

What the customer paid, or what the recipient was sent. Unchanged from what you requested.

charge

The MarzPay fee, in the same shape. Zero when no fee applies, for example airtime at cost.

net_amount

amount minus charge: what is credited to your merchant wallet. Present on collection payloads.

formatted vs raw

Render formatted in a UI. Do arithmetic with raw, and read currency from the same object instead of assuming the market currency.

Response shapes

Create calls return status, a human message, and a data object:

{
  "status": "success",
  "message": "Collection initiated successfully.",
  "data": {
    "transaction": { "uuid": "...", "reference": "...", "status": "processing" },
    "collection": { "amount": {}, "provider": "mtn", "phone_number": "+256..." }
  }
}

Errors use status: "error" with a stable error_code and, for field validation, an errors map:

{
  "status": "error",
  "message": "The given data was invalid.",
  "errors": {
    "reference": ["Reference is required and must be a valid UUID format."]
  }
}

{
  "status": "error",
  "message": "Reference already exists for API collection. Please use a different reference.",
  "error_code": "DUPLICATE_REFERENCE"
}

Transaction detail responses reuse the webhook envelope (event_type, transaction, plus a collection or disbursement object). Build one parser and use it for both paths.

Statuses

Status	Meaning	Is it final?
`pending`	Accepted, waiting on the provider or the customer	No
`processing`	Sent to the provider, outcome not known yet	No
`completed`	Money moved	Yes
`failed`	Provider or validation rejected it	Yes
`cancelled`	Customer or system cancelled it	Yes
`sandbox`	Sandbox mode create response, never a real transfer	Yes, for sandbox

Callbacks fire only for final statuses. A create call that returns processing still needs a webhook or a poll.

Errors you will actually hit

`error_code`	HTTP	Cause
`VALIDATION_ERROR`	422	Missing or malformed field, read `errors`
`INVALID_PHONE_FORMAT`	422	Number missing country code or wrong length
`DUPLICATE_REFERENCE`	422	UUID already used
`INVALID_REFERENCE_FORMAT`	422	Reference is not a UUID v4
`SERVICE_NOT_SUBSCRIBED`	403	No active subscription for that product
`INSUFFICIENT_BALANCE`	422	Wallet cannot cover amount plus charge
`ACCOUNT_FROZEN`	403	Business account frozen
`FORBIDDEN`	403	IP not whitelisted for a payout endpoint
`TRANSACTION_NOT_FOUND`	404	Unknown UUID, reference, or provider ID
`PROCESSING_TRANSFER_EXISTS`	422	Bank transfer already in flight
`API_CONNECTION_FAILED`	500	Provider call failed, balance refunded

Pagination

List endpoints accept page and per_page and return a pagination block:

{
  "pagination": {
    "current_page": 1,
    "last_page": 5,
    "per_page": 10,
    "total": 50,
    "from": 1,
    "to": 10
  }
}

per_page is capped at 100. Filters vary by product: type, status, provider, start_date, end_date, reference, and msisdn.

Permissions and limits

IP whitelist

Balance, send money, bank transfer, and airtime endpoints require your server IP on the API whitelist. Add it in dashboard settings before you deploy.

Subscriptions

Every provider product is subscribed per market in the marketplace. GET /collect-money/services shows what your business can currently accept.

Amount limits

Uganda collections accept 500 to 10,000,000 UGX. Other markets use your business limits, which you can read from the product services endpoints.

One transfer at a time

Bank transfers allow a single pending or processing transfer per business. Wait for the outcome before creating the next.

Next: sandbox mode

Exercise all of this without moving real money.

Get started

Collections

Disbursements

Bills & airtime

Webhooks & platform

Build tools

Support

Authentication

Request conventions

The money envelope

Response shapes

Statuses

Errors you will actually hit

Permissions and limits

IP whitelist

Subscriptions

Amount limits

One transfer at a time

Next: sandbox mode

​Authentication

​Request conventions

​The money envelope

​Response shapes

​Statuses

​Errors you will actually hit

​Pagination

​Permissions and limits

IP whitelist

Subscriptions

Amount limits

One transfer at a time

Next: sandbox mode

Authentication

Request conventions

The money envelope

Response shapes

Statuses

Errors you will actually hit

Pagination

Permissions and limits