Payment Links API

Create and manage payment links for easy payment collection using Marz Pay

Overview

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

How Payment Links Work

  1. Create a payment link with your desired amount and settings
  2. Share the generated URL with your customers
  3. Customers visit the link and complete their payment
  4. You receive notifications and can track all payments

API Base URL

All payment link API requests should be made to the following base URL:

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 Payment Link

Create a new payment link with customizable settings.

Endpoint

POST /api/v1/payment-links

Request Headers

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
type string Yes Type: "payment", "donation", or "subscription"
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")
description string No Description of the payment
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")
collection_methods array No Available payment methods: ["mobile_money", "card", "bank_transfer"]

Success Response

{
  "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",
    "collection_methods": ["mobile_money", "card"],
    "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 /api/v1/payment-links/{uuid}

Response

{
  "success": true,
  "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",
    "payment_url": "https://wallet.wearemarz.com/pay/550e8400-e29b-41d4-a716-446655440000",
    "is_active": true,
    "expiry_date": "2024-12-31T00:00:00.000000Z",
    "created_at": "2024-01-15T10:30:00.000000Z",
    "updated_at": "2024-01-15T10:30:00.000000Z"
  }
}

List Payment Links

Retrieve a list of all your payment links.

Endpoint

GET /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)

Response

{
  "success": true,
  "data": {
    "current_page": 1,
    "data": [
      {
        "id": 1,
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "title": "School Fees Payment",
        "type": "payment",
        "amount": "50000",
        "currency": "UGX",
        "payment_url": "https://wallet.wearemarz.com/pay/550e8400-e29b-41d4-a716-446655440000",
        "is_active": true,
        "created_at": "2024-01-15T10:30:00.000000Z"
      }
    ],
    "first_page_url": "https://wallet.wearemarz.com/api/v1/payment-links?page=1",
    "from": 1,
    "last_page": 1,
    "last_page_url": "https://wallet.wearemarz.com/api/v1/payment-links?page=1",
    "next_page_url": null,
    "path": "https://wallet.wearemarz.com/api/v1/payment-links",
    "per_page": 15,
    "prev_page_url": null,
    "to": 1,
    "total": 1
  }
}

Update Payment Link

Update an existing payment link's settings.

Endpoint

PUT /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
}

All fields are optional. Only include the fields you want to update.

Delete Payment Link

Permanently delete a payment link.

Endpoint

DELETE /api/v1/payment-links/{uuid}

Response

{
  "success": true,
  "message": "Payment link deleted successfully"
}

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 will 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 will show an appropriate message to customers. Active links can be used until the expiry date.

Code Examples

cURL - Create Payment Link

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

  • Use descriptive titles and descriptions to help customers understand what they're paying for
  • Set appropriate expiry dates to prevent stale payment links
  • Implement webhook callbacks to handle payment notifications in real-time
  • Use redirect URLs to provide better user experience after payment completion
  • Monitor payment link usage and deactivate unused links to maintain security
  • Store API keys securely and never expose them in client-side code