List Payment Links

Retrieve multiple payment links with pagination and filtering options.

Endpoint

GET /v1/payment-links

Authentication

Requires API key authentication via X-API-Key header.

Query Parameters

Parameter	Type	Required	Description
lim	integer	No	Items per page (positive integer, default: 10)
off	integer	No	Offset from start (non-negative integer, default: 0)
status	string	No	Filter by status (pending, completed, cancelled, expired)
isTest	boolean	No	Filter by test mode (true or false)

Request Examples

Basic Request

cURL Example

curl -X GET "https://api-pay.zelta.dev/v1/payment-links" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json"

Node.js Example

const response = await fetch('https://api-pay.zelta.dev/v1/payment-links', {
  method: 'GET',
  headers: {
    'X-API-Key': 'your-api-key-here',
    'Content-Type': 'application/json'
  }
});

const result = await response.json();
console.log(result);

Python Example

import requests

headers = {
    'X-API-Key': 'your-api-key-here',
    'Content-Type': 'application/json'
}

response = requests.get('https://api-pay.zelta.dev/v1/payment-links', headers=headers)
result = response.json()
print(result)

Request with Pagination

cURL Example

curl -X GET "https://api-pay.zelta.dev/v1/payment-links?lim=20&off=20" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json"

Node.js Example

const response = await fetch('https://api-pay.zelta.dev/v1/payment-links?lim=20&off=20', {
  method: 'GET',
  headers: {
    'X-API-Key': 'your-api-key-here',
    'Content-Type': 'application/json'
  }
});

const result = await response.json();
console.log(result);

Request with Filters

cURL Example

curl -X GET "https://api-pay.zelta.dev/v1/payment-links?status=completed&isTest=false" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json"

Node.js Example

const response = await fetch('https://api-pay.zelta.dev/v1/payment-links?status=completed&isTest=false', {
  method: 'GET',
  headers: {
    'X-API-Key': 'your-api-key-here',
    'Content-Type': 'application/json'
  }
});

const result = await response.json();
console.log(result);

Response Format

Success Response

{
  "success": true,
  "data": {
    "paymentLinks": [
      {
        "id": "pl_1234567890abcdef",
        "paymentLinkUrl": "https://pay.zelta.dev/abc123",
        "customerName": "John Doe",
        "concept": "Consulting Service",
        "amount": 2500,
        "status": "pending",
        "createdAt": "2024-01-15T10:30:00.000Z",
        "expiresAt": "2024-01-22T10:30:00.000Z",
        "cancelledAt": null,
        "completedAt": null,
        "isTest": true,
        "redirectUrl": "https://myapp.com/success",
        "metadata": {
          "orderId": "ORD-001",
          "service": "consulting"
        }
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 10,
      "total": 25,
      "totalPages": 3,
      "hasNext": true,
      "hasPrev": false
    }
  },
  "message": "Payment links retrieved successfully",
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Response Fields

Payment Link Object

Field	Type	Description
id	string	Unique payment link identifier
paymentLinkUrl	string	URL for the payment link
customerName	string	Name of the customer
customerEmail	string|null	Customer’s email address
concept	string	Description of what’s being paid for
amount	integer	Amount in cents
status	string	Payment link status
createdAt	string	ISO 8601 timestamp of creation
expiresAt	string	ISO 8601 timestamp of expiration
cancelledAt	string|null	ISO 8601 timestamp of cancellation
completedAt	string|null	ISO 8601 timestamp of completion
isTest	boolean	Whether this is a test payment
redirectUrl	string|null	Custom redirect URL
metadata	object|null	Custom metadata

Pagination Object

Field	Type	Description
page	integer	Current page number
limit	integer	Items per page
total	integer	Total number of items
totalPages	integer	Total number of pages
hasNext	boolean	Whether there’s a next page
hasPrev	boolean	Whether there’s a previous page

Status Codes

Code	Description
200	OK - Payment links retrieved successfully
400	Bad Request - Invalid query parameters
401	Unauthorized - Missing or invalid API key
403	Forbidden - Account suspended
429	Too Many Requests - Rate limit exceeded

Error Responses

Invalid Query Parameters

{
  "success": false,
  "message": "Validation error",
  "error": {
    "code": "ERR_VALIDATION_FAILED",
    "details": "Limit cannot exceed 100"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Missing API Key

{
  "success": false,
  "message": "Missing X-API-Key header",
  "error": {
    "code": "ERR_MISSING_API_KEY"
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Implementation Examples

Basic Payment Links Retrieval

Node.js Example

async function getAllPaymentLinks(apiKey, options = {}) {
  try {
    const params = new URLSearchParams();

    if (options.lim) params.append('lim', options.lim);
    if (options.off) params.append('off', options.off);
    if (options.status) params.append('status', options.status);
    if (options.isTest !== undefined) params.append('isTest', options.isTest);

    const url = `https://api-pay.zelta.dev/v1/payment-links?${params}`;

    const response = await fetch(url, {
      method: 'GET',
      headers: {
        'X-API-Key': apiKey,
        'Content-Type': 'application/json'
      }
    });

    const result = await response.json();

    if (!response.ok) {
      throw new Error(result.message);
    }

    return result.data;
  } catch (error) {
    console.error('Error retrieving payment links:', error);
    throw error;
  }
}

// Usage
const data = await getAllPaymentLinks('your-api-key');
console.log('Payment links:', data.paymentLinks);
console.log('Pagination:', data.pagination);

Python Example

import requests

def get_all_payment_links(api_key, options=None):
    try:
        params = {}

        if options:
            if 'lim' in options:
                params['lim'] = options['lim']
            if 'off' in options:
                params['off'] = options['off']
            if 'status' in options:
                params['status'] = options['status']
            if 'isTest' in options:
                params['isTest'] = options['isTest']

        headers = {
            'X-API-Key': api_key,
            'Content-Type': 'application/json'
        }

        response = requests.get(
            'https://api-pay.zelta.dev/v1/payment-links',
            headers=headers,
            params=params
        )

        result = response.json()

        if not response.ok:
            raise Exception(result['message'])

        return result['data']
    except Exception as error:
        print(f'Error retrieving payment links: {error}')
        raise

# Usage
data = get_all_payment_links('your-api-key')
print('Payment links:', data['paymentLinks'])
print('Pagination:', data['pagination'])

Paginated Retrieval

Node.js Example

async function getAllPaymentLinksPaginated(apiKey) {
  try {
    let allPaymentLinks = [];
    let off = 0;
    const lim = 100;
    let hasNext = true;

    while (hasNext) {
      const data = await getAllPaymentLinks(apiKey, { lim, off });

      allPaymentLinks = allPaymentLinks.concat(data.paymentLinks);
      hasNext = data.pagination.hasNext;
      off += lim;
    }

    return allPaymentLinks;
  } catch (error) {
    console.error('Error retrieving all payment links:', error);
    throw error;
  }
}

// Usage
const allLinks = await getAllPaymentLinksPaginated('your-api-key');
console.log(`Retrieved ${allLinks.length} payment links`);

Python Example

def get_all_payment_links_paginated(api_key):
    try:
        all_payment_links = []
        off = 0
        lim = 100
        has_next = True

        while has_next:
            data = get_all_payment_links(api_key, {'lim': lim, 'off': off})

            all_payment_links.extend(data['paymentLinks'])
            has_next = data['pagination']['hasNext']
            off += lim

        return all_payment_links
    except Exception as error:
        print(f'Error retrieving all payment links: {error}')
        raise

# Usage
all_links = get_all_payment_links_paginated('your-api-key')
print(f'Retrieved {len(all_links)} payment links')

Filtered Retrieval

Node.js Example

async function getPaymentLinksByStatus(apiKey, status) {
  try {
    const data = await getAllPaymentLinks(apiKey, { status });
    return data.paymentLinks;
  } catch (error) {
    console.error('Error retrieving payment links by status:', error);
    throw error;
  }
}

async function getTestPaymentLinks(apiKey) {
  try {
    const data = await getAllPaymentLinks(apiKey, { isTest: true });
    return data.paymentLinks;
  } catch (error) {
    console.error('Error retrieving test payment links:', error);
    throw error;
  }
}

// Usage
const completedLinks = await getPaymentLinksByStatus('your-api-key', 'completed');
const testLinks = await getTestPaymentLinks('your-api-key');

Python Example

def get_payment_links_by_status(api_key, status):
    try:
        data = get_all_payment_links(api_key, {'status': status})
        return data['paymentLinks']
    except Exception as error:
        print(f'Error retrieving payment links by status: {error}')
        raise

def get_test_payment_links(api_key):
    try:
        data = get_all_payment_links(api_key, {'isTest': True})
        return data['paymentLinks']
    except Exception as error:
        print(f'Error retrieving test payment links: {error}')
        raise

# Usage
completed_links = get_payment_links_by_status('your-api-key', 'completed')
test_links = get_test_payment_links('your-api-key')

Use Cases

1. Dashboard Overview

Get recent payment links for dashboard display:

async function getDashboardData(apiKey) {
  try {
    // Get recent payment links (last 20)
    const recentData = await getAllPaymentLinks(apiKey, { lim: 20 });

    // Get completed payments for this month
    const completedData = await getAllPaymentLinks(apiKey, {
      status: 'completed',
      lim: 100
    });

    // Calculate totals
    const totalCompleted = completedData.paymentLinks.reduce((sum, link) => sum + link.amount, 0);
    const completedCount = completedData.paymentLinks.length;

    return {
      recentLinks: recentData.paymentLinks,
      totalCompleted,
      completedCount,
      pagination: recentData.pagination
    };
  } catch (error) {
    console.error('Error getting dashboard data:', error);
    throw error;
  }
}

// Usage
const dashboardData = await getDashboardData('your-api-key');
console.log('Dashboard data:', dashboardData);

2. Order Management

Get payment links for specific orders:

async function getOrderPaymentLinks(apiKey, orderIds) {
  try {
    // Get all payment links
    const allLinks = await getAllPaymentLinksPaginated(apiKey);

    // Filter by order IDs
    const orderLinks = allLinks.filter(link =>
      link.metadata?.orderId && orderIds.includes(link.metadata.orderId)
    );

    return orderLinks;
  } catch (error) {
    console.error('Error getting order payment links:', error);
    throw error;
  }
}

// Usage
const orderLinks = await getOrderPaymentLinks('your-api-key', ['ORD-001', 'ORD-002']);
console.log('Order payment links:', orderLinks);

3. Customer Payment History

Get payment history for a specific customer:

async function getCustomerPaymentHistory(apiKey, customerId) {
  try {
    // Get all payment links
    const allLinks = await getAllPaymentLinksPaginated(apiKey);

    // Filter by customer ID
    const customerLinks = allLinks.filter(link =>
      link.metadata?.customerId === customerId
    );

    // Sort by creation date (newest first)
    customerLinks.sort((a, b) => new Date(b.createdAt) - new Date(a.createdAt));

    return customerLinks;
  } catch (error) {
    console.error('Error getting customer payment history:', error);
    throw error;
  }
}

// Usage
const customerHistory = await getCustomerPaymentHistory('your-api-key', 'CUST-123');
console.log('Customer payment history:', customerHistory);

4. Analytics and Reporting

Generate payment analytics:

async function generatePaymentAnalytics(apiKey) {
  try {
    // Get all payment links
    const allLinks = await getAllPaymentLinksPaginated(apiKey);

    // Calculate analytics
    const analytics = {
      total: allLinks.length,
      completed: allLinks.filter(link => link.status === 'completed').length,
      pending: allLinks.filter(link => link.status === 'pending').length,
      cancelled: allLinks.filter(link => link.status === 'cancelled').length,
      expired: allLinks.filter(link => link.status === 'expired').length,
      totalAmount: allLinks
        .filter(link => link.status === 'completed')
        .reduce((sum, link) => sum + link.amount, 0),
      averageAmount: 0,
      statusDistribution: {},
      monthlyTrends: {}
    };

    // Calculate average amount
    if (analytics.completed > 0) {
      analytics.averageAmount = analytics.totalAmount / analytics.completed;
    }

    // Calculate status distribution
    allLinks.forEach(link => {
      analytics.statusDistribution[link.status] =
        (analytics.statusDistribution[link.status] || 0) + 1;
    });

    // Calculate monthly trends
    allLinks.forEach(link => {
      const month = new Date(link.createdAt).toISOString().substring(0, 7); // YYYY-MM
      if (!analytics.monthlyTrends[month]) {
        analytics.monthlyTrends[month] = 0;
      }
      analytics.monthlyTrends[month]++;
    });

    return analytics;
  } catch (error) {
    console.error('Error generating payment analytics:', error);
    throw error;
  }
}

// Usage
const analytics = await generatePaymentAnalytics('your-api-key');
console.log('Payment analytics:', analytics);

Best Practices

1. Pagination Strategy

Use appropriate page sizes for your use case:

// For dashboard: small pages
const dashboardData = await getAllPaymentLinks(apiKey, { lim: 20 });

// For bulk operations: larger pages
const bulkData = await getAllPaymentLinks(apiKey, { lim: 100 });

// For complete dataset: paginated retrieval
const allData = await getAllPaymentLinksPaginated(apiKey);

2. Caching

Cache frequently accessed data:

const paymentLinkCache = new Map();

async function getCachedPaymentLinks(apiKey, cacheKey, ttl = 300000) { // 5 minutes
  const cached = paymentLinkCache.get(cacheKey);

  if (cached && Date.now() - cached.timestamp < ttl) {
    return cached.data;
  }

  const data = await getAllPaymentLinks(apiKey);

  paymentLinkCache.set(cacheKey, {
    data: data,
    timestamp: Date.now()
  });

  return data;
}

3. Error Handling

Handle different error scenarios:

async function getPaymentLinksSafely(apiKey, options = {}) {
  try {
    return await getAllPaymentLinks(apiKey, options);
  } catch (error) {
    if (error.message.includes('rate limit')) {
      // Implement retry logic
      await new Promise(resolve => setTimeout(resolve, 1000));
      return await getAllPaymentLinks(apiKey, options);
    }

    throw error;
  }
}

4. Rate Limiting

Implement rate limiting for batch operations:

async function getPaymentLinksWithRateLimit(apiKey, options = {}, delay = 1000) {
  try {
    const data = await getAllPaymentLinks(apiKey, options);

    // Rate limiting delay
    await new Promise(resolve => setTimeout(resolve, delay));

    return data;
  } catch (error) {
    console.error('Error with rate limiting:', error);
    throw error;
  }
}

Testing

Test Pagination

Test pagination functionality:

// Test first page
const page1 = await getAllPaymentLinks('your-api-key', { lim: 5, off: 0 });

// Test second page
const page2 = await getAllPaymentLinks('your-api-key', { lim: 5, off: 5 });

// Test pagination info
console.log('Page 1:', page1.pagination);
console.log('Page 2:', page2.pagination);

Test Filters

Test filtering functionality:

// Test status filter
const completedLinks = await getAllPaymentLinks('your-api-key', { status: 'completed' });

// Test test mode filter
const testLinks = await getAllPaymentLinks('your-api-key', { isTest: true });

// Test combined filters
const completedTestLinks = await getAllPaymentLinks('your-api-key', {
  status: 'completed',
  isTest: true
});

Related Endpoints

• Get Payment Link - Retrieve a single payment link
• Create Payment Link - Create a new payment link
• Cancel Payment Link - Cancel a payment link