MarzPay API Documentation

Overview

Card payments use the same Collect Money API with method set to card. You do not send a phone number. The API returns a redirect_url; you send the customer to that URL to complete payment on the card gateway. After payment, the customer can be returned to your callback_url, and you receive a server-to-server webhook with the result.

Flow

POST to /api/v1/collect-money with method = card, amount, country, and a unique reference
API returns redirect_url (e.g. https://wallet.wearemarz.com/pay/card-gateway?reference=...)
Send the customer to redirect_url (open in browser or redirect)
Customer completes payment on the card gateway
You receive a callback to your callback_url and/or webhook with the result

API Base URL

https://wallet.wearemarz.com/api/v1

Create card collection

Send a POST request to /collect-money with the following parameters.

POST /collect-money

Request parameters (card)

amount (required) – Amount in UGX (500 – 10,000,000)
method (required for card) – Set to card
reference (required) – Unique UUID for this collection
country (required) – Country code, e.g. UG
description (optional) – Description for the payment
callback_url (optional) – URL to send the customer after payment; also used for server-to-server callback

Do not send phone_number for card payments.

Example request

curl -X POST 'https://wallet.wearemarz.com/api/v1/collect-money' \
  -H 'Authorization: Basic YOUR_BASE64_API_CREDENTIALS' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 5000,
    "method": "card",
    "reference": "123e4567-e89b-12d3-a456-426614174000",
    "country": "UG",
    "description": "Order payment",
    "callback_url": "https://your-app.com/thank-you"
  }'

Example response

{
  "status": "success",
  "message": "Card collection initiated. Redirect the customer to redirect_url.",
  "data": {
    "transaction": {
      "uuid": "a799c628-f52a-4540-8b77-43509f2775d3",
      "reference": "b59d3d6d-5827-41ee-b455-18dd20ef1c8a",
      "status": "pending"
    },
    "redirect_url": "https://wallet.wearemarz.com/pay/card-gateway?..."
  }
}

Send the customer to data.redirect_url (same tab, new tab, or redirect). Use the exact URL returned by the API—do not modify it or build it yourself.

Requirements

Your business must have an active Card Payments subscription (for the country, e.g. UG, or GLOBAL)
Use a unique UUID reference for each collection
Use the redirect_url from the response as-is

Card Wallet

Card payment collections are credited to a separate card wallet (card_balance), not the main wallet. Every business has two wallets:

Wallet	Source	Description
Main Wallet	Mobile money (MTN, Airtel)	Collections from mobile money, disbursements
Card Wallet	Card payments	All card payment collections go here

How it works

Customer pays via card on the payment gateway
Net amount (after charge) is immediately credited to your card wallet
The charge is credited to the platform's card wallet
Funds are available for bank transfer withdrawal

Withdrawing card wallet funds

Card wallet funds can be withdrawn via bank transfer. Pass wallet_source = card when creating a bank transfer:

POST /api/v1/bank-transfer
{
  "amount": 50000,
  "bank_name": "Stanbic Bank",
  "bank_account_number": "9030012345678",
  "description": "Card revenue withdrawal",
  "wallet_source": "card"
}

See the Bank Transfer documentation for full details.

Balance API

The GET /api/v1/balance endpoint returns both wallets:

{
  "available_balance": { "raw": 150000, "currency": "UGX" },
  "card_balance": { "raw": 35000, "currency": "UGX", "description": "Card wallet balance" },
  "total_balance": { "raw": 185000, "currency": "UGX" }
}

Callbacks & webhooks

Card payments use the same callback and webhook format as other collections. The customer can be redirected to your callback_url after payment. Your server will also receive a POST request (webhook) with the transaction result—same structure as collections, with provider set to "card payments" and phone_number possibly null.

For the exact callback payload and examples (completed/failed), see the Webhooks documentation.

Card Payments