Card Payments

Collect payments from customers using debit or credit cards via the MarzPay card gateway. 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

Initialize collection

POST to /api/v1/collect-money with method: card, amount, country, and a unique reference.

Get redirect URL

The API returns a redirect_url (e.g. https://wallet.wearemarz.com/pay/card-gateway?reference=...).

Send customer to gateway

Open redirect_url in the browser (same tab, new tab, or redirect). Use the exact URL returned by the API - do not modify or build it yourself.

Customer pays

The customer completes payment on the card gateway.

Receive result

The customer is redirected to your callback_url, and you receive a webhook with the transaction result.

Create a card collection

Endpoint POST https://wallet.wearemarz.com/api/v1/collect-money Authentication is HTTP Basic: Authorization: Basic base64(api_key:api_secret). Request parameters (card)

Parameter	Type	Required	Description
amount	number	Yes	Amount in UGX (500 – 10,000,000)
method	string	Yes	Set to `card`
reference	string	Yes	Unique UUID v4 reference for this collection
country	string	Yes	Country code, e.g. `UG`
description	string	No	Description for the payment
callback_url	string	No	URL to send the customer after payment; also used for server-to-server callback

Do not send phone_number for card payments. Example request

Tab Title
Tab Title

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"
}'

const credentials = Buffer.from(`${apiKey}:${apiSecret}`).toString("base64");

const response = await fetch("https://wallet.wearemarz.com/api/v1/collect-money", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: `Basic ${credentials}`,
  },
  body: JSON.stringify({
    amount: 5000,
    method: "card",
    reference: "123e4567-e89b-12d3-a456-426614174000",
    country: "UG",
    description: "Order payment",
    callback_url: "https://your-app.com/thank-you",
  }),
});

const data = await response.json();
console.log(data.data.redirect_url);

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?..."
  }
}

Requirements

Active subscription

Your business must have an active Card Payments subscription (for the country, e.g. UG, or GLOBAL).

Unique reference

Use a unique UUID reference for each collection.

Redirect URL

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	Collections from mobile money, disbursements
Card Wallet	Card payments	All card payment collections go here

Withdrawing card wallet funds

Card wallet funds can be withdrawn via bank transfer. Pass wallet_source = card when creating a 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 also receives a POST 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 use the same callback format as other collections. See Webhooks for the signing headers (X-MarzPay-Timestamp, X-MarzPay-Signature) and verification steps.

Get started

Collections

Disbursements

Bills & airtime

Webhooks & platform

Build tools

Support

Flow

Create a card collection

Requirements

Active subscription

Unique reference

Redirect URL

Card wallet

Withdrawing card wallet funds

Balance API

Callbacks & webhooks

​Flow

​Create a card collection

​Requirements

Active subscription

Unique reference

Redirect URL

​Card wallet

​Withdrawing card wallet funds

​Balance API

​Callbacks & webhooks

Flow

Create a card collection

Requirements

Card wallet

Withdrawing card wallet funds

Balance API

Callbacks & webhooks