Fikra API Billing: Token-Credit Wallet and Paystack Integration

Overview

Fikra API uses a token-credit wallet system for billing. This means you purchase credits (tokens) in advance, and your API requests deduct from this balance. Fikra has a Paystack billing integration, and the public site states that M-Pesa and cards are accepted for top-ups.

Note: If you are looking for a specific payment method not listed above (e.g., direct bank transfer, crypto, or other regional methods), please confirm availability with Fikra support before attempting to use it. Do not assume unsupported methods will work.

What is a Token-Credit Wallet?

A token-credit wallet is a prepaid balance system. Instead of paying per request in real-time, you: 1. Top up your account with credits. 2. Make API calls, which consume credits based on the tokens used. 3. Monitor your remaining balance to avoid service interruption.

This model provides predictable costs and avoids unexpected billing surprises.

Account and Top-Up Flow

1. Create an Account: Sign up on the Fikra dashboard at https://fikraapi.co.ke.
2. Generate an API Key: Create a new API key in the dashboard. Store it securely.
3. Top Up Your Wallet: Navigate to the billing section in the dashboard. Use the available payment methods (M-Pesa or card via Paystack) to add credits to your wallet.
4. Verify Balance: Confirm that your token balance has been updated after the payment is processed.

Monitoring Balance and Handling HTTP 402

Developers should implement balance monitoring to prevent service disruptions:

• Check Balance: Periodically query your account balance via the Fikra dashboard or any available API endpoint for balance checks.
• Handle HTTP 402: If your token balance is insufficient, the API will return an HTTP 402 (Payment Required) status code. Your application should:
• Log the error.
• Notify the user or system administrator that the balance is low.
• Pause or queue requests until the balance is topped up.

Example error handling in Python:

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.fikraapi.co.ke/v1",
    api_key=os.getenv("FIKRA_API_KEY")
)

try:
    response = client.chat.completions.create(
        model="fikra-flash",
        messages=[{"role": "user", "content": "Hello"}]
    )
    print(response.choices[0].message.content)
except Exception as e:
    if "402" in str(e):
        print("Error: Insufficient token balance. Please top up your wallet.")
    else:
        print(f"Error: {e}")

Security Advice

• Never expose your Fikra API key in browser code. API keys should only be used in server-side applications or secure backend environments.
• Use environment variables: Store your API key in environment variables (e.g., FIKRA_API_KEY) rather than hardcoding it in your source code.
• Rotate keys regularly: If you suspect a key has been compromised, rotate it immediately in the Fikra dashboard.

Summary

Fikra API offers a straightforward token-credit wallet system with Paystack integration for M-Pesa and card payments. Monitor your balance, handle HTTP 402 errors gracefully, and keep your API keys secure to ensure reliable and safe API usage.