QBitFlow

    QBitFlow Documentation

    Complete guide to integrating cryptocurrency payments with QBitFlow

    Best Practices & Advanced Topics

    Follow these best practices to build robust, production-ready integrations with QBitFlow.

    Security Best Practices

    Protect Your API Keys

    Never expose API keys in client-side code or public repositories. Store them as environment variables and restrict access to authorized personnel only.

    Validate Webhook Signatures

    Always verify webhook signatures before processing. This prevents malicious actors from sending fake payment notifications to your server.

    Environment Variables Example

    Secure API Key Storage
    import os
    from qbitflow import QBitFlow
    

    # Load API key from environment variable
    API_KEY = os.getenv('QBITFLOW_API_KEY')
    if not API_KEY:
        raise ValueError("QBITFLOW_API_KEY environment variable not set")
    

    client = QBitFlow(api_key=API_KEY)

    Error Handling

    Always implement proper error handling to gracefully handle API failures, network issues, and validation errors.

    Comprehensive Error Handling
    from qbitflow import QBitFlow
    from qbitflow.exceptions import (
    	QBitFlowError,
    	AuthenticationError,
    	NotFoundException,
    	ValidationError,
    	RateLimitError,
    	NetworkError,
    	APIError
    )
    

    client = QBitFlow(api_key="your_api_key")
    

    try:
    	payment = client.one_time_payments.get("non-existent-uuid")
    except AuthenticationError:
    	print("Invalid API key or authentication failed")
    except NotFoundException as e:
    	print(f"Payment not found: {e.message}")
    except ValidationError as e:
    	print(f"Validation error: {e.message}")
    except RateLimitError as e:
    	print(f"Rate limit exceeded: {e.message}")
    	if e.response and 'retry_after' in e.response:
    		print(f"Retry after {e.response['retry_after']} seconds")
    except NetworkError as e:
    	print(f"Network error: {e.message}")
    except APIError as e:
    	print(f"API error: {e.message} (status: {e.status_code})")
    except QBitFlowError as e:
    	print(f"SDK error: {e.message}")

    Database Integration

    Store Critical Information

    Always store payment and subscription information in your database. Don't rely solely on QBitFlow's API for historical data. Store customer UUIDs, transaction UUIDs, subscription statuses, and relevant metadata.

    Recommended Database Schema

    -- Customers table
    CREATE TABLE customers (
      id SERIAL PRIMARY KEY,
      qbitflow_uuid VARCHAR(255) UNIQUE NOT NULL,
      email VARCHAR(255) NOT NULL,
      name VARCHAR(255),
      created_at TIMESTAMP DEFAULT NOW()
      -- ...
    );
    

    -- Payments table
    CREATE TABLE payments (
      id SERIAL PRIMARY KEY,
      customer_id INTEGER REFERENCES customers(id),
      qbitflow_payment_uuid VARCHAR(255) UNIQUE NOT NULL,
      product_name VARCHAR(255) NOT NULL,
      amount DECIMAL(10, 2) NOT NULL,
      currency VARCHAR(10) NOT NULL,
      transaction_hash VARCHAR(255),
      created_at TIMESTAMP DEFAULT NOW(),
      completed_at TIMESTAMP
      -- ...
    );
    

    -- Subscriptions table
    CREATE TABLE subscriptions (
      id SERIAL PRIMARY KEY,
      customer_id INTEGER REFERENCES customers(id),
      qbitflow_subscription_uuid VARCHAR(255) UNIQUE NOT NULL,
      product_name VARCHAR(255) NOT NULL,
      price DECIMAL(10, 2) NOT NULL,
      frequency VARCHAR(50) NOT NULL,
      status VARCHAR(50) NOT NULL,
      next_billing_date TIMESTAMP,
      last_billing_date TIMESTAMP,
      created_at TIMESTAMP DEFAULT NOW(),
      cancelled_at TIMESTAMP
      -- ...
    );

    Notification Strategy

    Keep Customers Informed

    Set up automated notifications to keep customers informed about their payments and subscriptions. This reduces support requests and improves customer satisfaction.

    ✅ Payment Successful

    Send confirmation email with transaction details, receipt, and access instructions.

    🔄 Subscription Created

    Welcome email with subscription details, billing schedule, and management link.

    ⚠️ Low Allowance Warning

    Remind customer to increase allowance before next billing cycle.

    🚨 Max Amount Reached

    Urgent notification requiring immediate action to update max amount.

    ❌ Payment Failed

    Inform customer of failed payment and provide troubleshooting steps.

    Performance Optimization

    Use Pagination

    When fetching lists of payments or subscriptions, always use pagination to avoid loading too much data at once. This improves performance and reduces API costs.

    Cache Session Data

    Session checkout details don't change frequently. Cache them for a short period to reduce API calls when customers refresh the checkout page.

    Production Checklist

    Webhook endpoint is live and accessible

    Test with ngrok or similar tool during development

    Success and cancel URLs are configured

    Provide good user experience after payment

    Error handling is comprehensive

    Handle all exception types gracefully

    Database schema is set up

    Store payments, subscriptions, and customer data

    Notification system is configured

    Email customers about important events

    Cron job for subscription monitoring

    Daily checks for subscription status changes

    API keys are secured

    Stored as environment variables, not in code

    Testing in sandbox environment

    Test all flows before going live

    Monitoring & Analytics

    Track Key Metrics

    Monitor important metrics to understand your payment performance and customer behavior. Track conversion rates, failed payment rates, subscription churn, and revenue trends.

    Payment Success RateTrack completed vs. failed
    Subscription Churn RateMonitor cancellations
    Allowance IssuesTrack low_on_funds occurrences
    Average Transaction ValueMeasure revenue per payment

    🎉 You're Ready! Follow these best practices, and you'll have a robust, production-ready QBitFlow integration. If you have questions, reach out to our support team at support@qbitflow.app or visit our documentation site.