Handling Payment Issues and Managing Your Fikra API Wallet

If you are encountering a "card declined" error or similar payment issues while trying to top up your Fikra API account, it is important to understand how Fikra handles billing. Fikra API operates on a token-credit wallet system integrated with Paystack. The public documentation states that M-Pesa and cards are accepted payment methods. However, specific card network support (such as Visa, Mastercard, or others) and regional availability can vary. If a specific card type or provider is not explicitly listed as a supported method in your dashboard, you should confirm its availability with Fikra support before attempting further transactions.

Understanding the Token-Credit Wallet

Fikra API does not bill you per request in real-time. Instead, you purchase a balance of token credits. When you make API calls, the cost of the tokens used is deducted from this wallet. If your wallet balance is insufficient to cover the cost of a request, the API will reject the request.

Safe Top-Up Flow

1. Access the Dashboard: Log in to your Fikra dashboard at https://fikraapi.co.ke.
2. Navigate to Billing: Go to the billing or wallet section.
3. Initiate Top-Up: Select the amount of credits you wish to purchase.
4. Choose Payment Method: Select either M-Pesa or Card. If using a card, ensure the card is valid and has sufficient funds. Note that payment processing is handled by Paystack.
5. Complete Transaction: Follow the prompts to authorize the payment. Once successful, your wallet balance will be updated.

Monitoring Balance and Handling HTTP 402

Developers should proactively monitor their wallet balance to avoid service interruptions. You can check your current balance via the Fikra dashboard or, if available, through API endpoints designed for account management.

If your balance is insufficient, the Fikra API will return an HTTP 402 (Payment Required) status code. Your application should handle this error gracefully:

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 wallet balance. Please top up your account.")
    else:
        print(f"An error occurred: {e}")

Security Advice

• Never expose your Fikra API key in browser code. API keys should only be used in server-side environments.
• Use environment variables: Store your FIKRA_API_KEY in environment variables or a secure secrets manager.
• Rotate keys: If you suspect a key has been compromised, generate a new key in the Fikra dashboard and revoke the old one.

For specific payment issues, such as a card being declined, check your bank statement for any holds or rejections, and ensure your card is enabled for online transactions. If the issue persists, contact Fikra support for assistance.