Payment Links

Payment Links allow you to create shareable payment URLs that customers can use to make payments directly. These links can be used for donations, product sales, subscriptions, and general payments.

How payment links work

Create a link

Create a payment link with your desired amount and settings.

Share the URL

Share the generated URL with your customers.

Customer pays

Customers visit the link and complete their payment.

Get notified

You receive notifications and can track all payments.

Pricing

Fees come from the public pricing page. Custom business rates may differ.

Supported markets

Payment links work in all 12 markets: Uganda, Kenya, Rwanda, Democratic Republic of the Congo, Zambia, Cameroon, Benin, Côte d’Ivoire, Gabon, Senegal, Sierra Leone, and Congo-Brazzaville. For Kenya M-Pesa links, set country: "KE" and currency: "KES". For DRC, use CD with CDF or USD.

API base URL

All payment link API requests should be made to: https://wallet.wearemarz.com/api/v1

Authentication

All API requests require authentication using your API key. Include the API key in the Authorization header with Basic Auth format. Authorization: Basic YOUR_API_CREDENTIALS Format: YOUR_API_CREDENTIALS = base64_encode("your_api_key:your_api_secret")

Create a payment link

Create a new payment link with customizable settings. Endpoint POST https://wallet.wearemarz.com/api/v1/payment-links Request headers

Header	Value
Content-Type	`application/json`
Authorization	`Basic YOUR_API_CREDENTIALS`

Request body

{
  "title": "School Fees Payment",
  "type": "payment",
  "amount": 50000,
  "is_fixed": true,
  "currency": "UGX",
  "description": "Payment for first term school fees",
  "redirect_url": "https://example.com/thank-you",
  "callback_url": "https://your-domain.com/webhook/payment-link",
  "expiry_date": "2024-12-31",
  "country": "UG",
  "collection_methods": ["mobile_money", "card"]
}

Parameters

Field	Type	Required	Description
title	string	Yes	Title of the payment link
slug	string	No	Custom public path, e.g. `school-fees` → `/pay/school-fees`. Auto-generated from the title if omitted.
type	string	No	Type: `payment`, `donation`, or `subscription` (default: `payment`)
amount	number	Conditional	Fixed amount (required if `is_fixed` is true)
minimum_amount	number	Conditional	Minimum amount (required if `is_fixed` is false)
is_fixed	boolean	No	Whether the amount is fixed (default: `true`)
currency	string	No	Currency code (default: `UGX`; use `KES`, `RWF`, `CDF`, `USD`, `ZMW`, `XAF`, `XOF`, or `SLE`)
description	string	No	Description of the payment (max 255 characters)
redirect_url	string	No	URL to redirect after successful payment
callback_url	string	No	Webhook URL for payment notifications
expiry_date	string	No	Expiry date in `YYYY-MM-DD` format
country	string	No	Country code (default: `UG`; use `KE`, `RW`, `CD`, `ZM`, `CM`, `BJ`, `CI`, `GA`, `CG`, `SN`, or `SL`)
collection_methods	array	No	Optional. Omit to enable all subscribed methods for that country. Accepts `mobile_money`, `card`, or provider names (`MTN`, `Airtel`, `Vodacom`, `Orange`, `M-Pesa`).

Success response

{
  "status": "success",
  "success": true,
  "message": "Payment link created successfully",
  "data": {
    "id": 1,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "title": "School Fees Payment",
    "type": "payment",
    "amount": "50000",
    "is_fixed": true,
    "currency": "UGX",
    "description": "Payment for first term school fees",
    "redirect_url": "https://example.com/thank-you",
    "callback_url": "https://your-domain.com/webhook/payment-link",
    "expiry_date": "2024-12-31T00:00:00.000000Z",
    "country": "UG",
    "method": "mobile_money_and_card",
    "collection_methods": ["MTN", "Airtel", "Card Payments"],
    "payment_url": "https://wallet.wearemarz.com/pay/550e8400-e29b-41d4-a716-446655440000",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z"
  }
}

Error response

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "title": ["The title field is required."],
    "amount": ["The amount field is required when is_fixed is true."]
  }
}

Get payment link details

Retrieve details of a specific payment link. Endpoint GET https://wallet.wearemarz.com/api/v1/payment-links/{uuid}

List payment links

Retrieve a list of all your payment links. Endpoint GET https://wallet.wearemarz.com/api/v1/payment-links Query parameters

Parameter	Type	Description
page	integer	Page number for pagination (default: 1)
per_page	integer	Number of items per page (default: 15, max: 100)
type	string	Filter by payment link type
status	string	Filter by status (`active`, `inactive`)

Update a payment link

Update an existing payment link’s settings. All fields are optional - only include the fields you want to update. Endpoint PUT https://wallet.wearemarz.com/api/v1/payment-links/{uuid} Request body

{
  "title": "Updated School Fees Payment",
  "amount": 75000,
  "description": "Updated payment for first term school fees",
  "is_active": false
}

Delete a payment link

Permanently delete a payment link. Endpoint DELETE https://wallet.wearemarz.com/api/v1/payment-links/{uuid}

Using payment links

Once created, payment links can be shared with customers through various channels.

Payment link URL format

https://wallet.wearemarz.com/pay/{uuid}

Fixed amount links

For fixed amount links, customers see the predetermined amount and can proceed directly to payment.

Variable amount links

For variable amount links, customers can enter their desired amount (above the minimum) before proceeding to payment.

Expiry handling

Expired links show an appropriate message to customers. Active links can be used until the expiry date.

Code examples

cURL

curl -X POST "https://wallet.wearemarz.com/api/v1/payment-links" \
  -H "Content-Type: application/json" \
  -H "Authorization: Basic YOUR_API_CREDENTIALS" \
  -d '{
  "title": "School Fees Payment",
  "type": "payment",
  "amount": 50000,
  "is_fixed": true,
  "currency": "UGX",
  "description": "Payment for first term school fees",
  "redirect_url": "https://example.com/thank-you",
  "callback_url": "https://your-domain.com/webhook/payment-link",
  "country": "UG"
}'

JavaScript (Fetch)

const response = await fetch("https://wallet.wearemarz.com/api/v1/payment-links", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Basic YOUR_API_CREDENTIALS",
  },
  body: JSON.stringify({
    title: "School Fees Payment",
    type: "payment",
    amount: 50000,
    is_fixed: true,
    currency: "UGX",
    description: "Payment for first term school fees",
    country: "UG",
  }),
});

const data = await response.json();

if (data.success) {
  console.log("Payment Link URL:", data.data.payment_url);
  console.log("Payment Link ID:", data.data.uuid);
} else {
  console.error("Error:", data.message);
}

PHP (Guzzle)

$client = new \GuzzleHttp\Client();

$response = $client->post("https://wallet.wearemarz.com/api/v1/payment-links", [
  "headers" => [
    "Content-Type" => "application/json",
    "Authorization" => "Basic YOUR_API_CREDENTIALS",
  ],
  "json" => [
    "title" => "School Fees Payment",
    "type" => "payment",
    "amount" => 50000,
    "is_fixed" => true,
    "currency" => "UGX",
    "description" => "Payment for first term school fees",
    "country" => "UG",
  ],
]);

$data = json_decode($response->getBody(), true);

if ($data["success"]) {
  echo "Payment Link URL: " . $data["data"]["payment_url"] . "\n";
  echo "Payment Link ID: " . $data["data"]["uuid"] . "\n";
} else {
  echo "Error: " . $data["message"] . "\n";
}

Error codes

Code	Description
400	Bad Request - Invalid request data or validation errors
401	Unauthorized - Invalid API credentials
403	Forbidden - Access denied to payment link
404	Not Found - Payment link not found
422	Unprocessable Entity - Validation failed
500	Internal Server Error

Best practices

Descriptive titles

Use descriptive titles and descriptions to help customers understand what they’re paying for.

Set expiry dates

Set appropriate expiry dates to prevent stale payment links.

Webhook callbacks

Implement webhook callbacks to handle payment notifications in real time.

Secure keys

Store API keys securely and never expose them in client-side code.

Get started

Collections

Disbursements

Bills & airtime

Webhooks & platform

Build tools

Support

How payment links work

Pricing

Supported markets

API base URL

Authentication

Create a payment link

Get payment link details

List payment links

Update a payment link

Delete a payment link

Using payment links

Payment link URL format

Fixed amount links

Variable amount links

Expiry handling

Code examples

cURL

JavaScript (Fetch)

PHP (Guzzle)

Error codes

Best practices

Descriptive titles

Set expiry dates

Webhook callbacks

Secure keys

​How payment links work

​Pricing

​Supported markets

​API base URL

​Authentication

​Create a payment link

​Get payment link details

​List payment links

​Update a payment link

​Delete a payment link

​Using payment links

​Payment link URL format

​Fixed amount links

​Variable amount links

​Expiry handling

​Code examples

​cURL

​JavaScript (Fetch)

​PHP (Guzzle)

​Error codes

​Best practices

Descriptive titles

Set expiry dates

Webhook callbacks

Secure keys

How payment links work

Pricing

Supported markets

API base URL

Authentication

Create a payment link

Get payment link details

List payment links

Update a payment link

Delete a payment link

Using payment links

Payment link URL format

Fixed amount links

Variable amount links

Expiry handling

Code examples

cURL

JavaScript (Fetch)

PHP (Guzzle)

Error codes

Best practices