Fees API

Retrieve current service fees and withdrawal charges with transparent pricing structure.

Base Endpoint

Get Fee Structure

Retrieve the complete fee structure including service fees and withdrawal charges for all transaction amounts.

Response Structure

Fee Object

Summary Object

Error Responses

Understanding Fees

Fee Calculation Examples

Example: Calculate Fee for KES 750 Transaction

// Fetch fees from API
const response = await fetch('/v3/fees/', {
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY'
  }
});

const data = await response.json();

// Find applicable fee for KES 750
const amount = 750;
const applicableFee = data.data.fees.find(fee => 
  amount >= fee.amount_range.from && amount <= fee.amount_range.to
);

if (applicableFee) {
  console.log(`Service Fee: KES ${applicableFee.service_fee}`);
  console.log(`Withdrawal Fee: KES ${applicableFee.withdrawal_fee}`);
  console.log(`Total with Service Fee: KES ${amount + applicableFee.service_fee}`);
}

PHP Example

function calculateFee($amount, $fees) {
    foreach ($fees as $fee) {
        if ($amount >= $fee['amount_range']['from'] && 
            $amount <= $fee['amount_range']['to']) {
            return $fee;
        }
    }
    return null;
}

// Usage
$amount = 750;
$applicableFee = calculateFee($amount, $feesData['fees']);
if ($applicableFee) {
    echo "Service Fee: KES {$applicableFee['service_fee']}\n";
    echo "Withdrawal Fee: KES {$applicableFee['withdrawal_fee']}\n";
}

Example Usage

cURL Example

curl -X GET "http://localhost/pay-app/v3/fees/" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

JavaScript/Node.js Example

const getFees = async () => {
  try {
    const response = await fetch('http://localhost/pay-app/v3/fees/', {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });

    const result = await response.json();
    
    if (result.success) {
      console.log('Fee Structure:', result.data.fees);
      console.log('Summary:', result.data.summary);
      
      // Display free tiers
      const freeTiers = result.data.fees.filter(fee => fee.service_fee === 0);
      console.log(`Found ${freeTiers.length} free service tiers`);
    } else {
      console.error('Error:', result.error);
    }
  } catch (error) {
    console.error('Network error:', error);
  }
};

getFees();

Python Example

import requests

def get_fees(api_key):
    headers = {
        'Authorization': f'Bearer {api_key}',
        'Content-Type': 'application/json'
    }
    
    response = requests.get('http://localhost/pay-app/v3/fees/', headers=headers)
    
    if response.status_code == 200:
        data = response.json()
        if data['success']:
            return data['data']
    return None

# Usage
api_key = 'YOUR_API_KEY'
fees_data = get_fees(api_key)

if fees_data:
    print(f"Total fee ranges: {fees_data['summary']['total_fee_ranges']}")
    for fee in fees_data['fees']:
        print(f"KES {fee['amount_range']['from']}-{fee['amount_range']['to']}: "
              f"Service Fee KES {fee['service_fee']}, "
              f"Withdrawal Fee KES {fee['withdrawal_fee']}")

Best Practices

• Cache Fee Data: Fee structures don't change frequently. Cache the response for improved performance.
• Pre-calculate Costs: Show users the total cost including fees before initiating transactions.
• Handle Edge Cases: Always validate that the transaction amount falls within supported ranges.
• Monitor Changes: Regularly sync fee structures to stay updated with any pricing changes.
• Error Handling: Implement proper error handling for API failures.

Related APIs

The Fees API works well with these other endpoints:

• Wallet API - Check service wallet balance before transactions
• STK Push API - Initiate payments with knowledge of service fees
• Pay-Request (B2C) API - Send money with withdrawal fee calculation
• Transactions API - Monitor fee deductions and transaction costs