Welcome to QBitFlow

QBitFlow is a comprehensive cryptocurrency payment processing platform that enables businesses and developers to accept crypto payments with ease. Whether you need one-time payments, recurring subscriptions, or pay-as-you-go billing, QBitFlow provides the tools you need.

Why Choose QBitFlow?

Key Features

Organization Structure & Roles

Understanding how organizations, users, and roles work in QBitFlow is essential for effective team collaboration and payment management.

Organization Hierarchy

User Roles

QBitFlow has three distinct user roles, each with different permissions and capabilities:

Organization-Level vs User-Level

Organization Fees for Users

API Keys and Permissions

Session Checkouts

Session checkouts are the foundation of accepting payments in QBitFlow. Learn how to create and manage checkout sessions for your customers.

What is a Session Checkout?

Creating Session Checkouts

You can create session checkouts for different types of payments:

1. One-Time Payment Session

Create One-Time Payment Session

Copy

Create a session for a single payment

PythonGoTypeScript

# Create a payment from an existing product
response = client.one_time_payments.create_session(
	product_id=1,
	customer_uuid="customer-uuid",  # optional
	webhook_url="https://your-domain.com/webhook",
)

# Or create a custom payment
response = client.one_time_payments.create_session(
	product_name="Custom Product",
	description="Product description",
	price=99.99,  # USD
	customer_uuid="customer-uuid",
	webhook_url="https://your-domain.com/webhook",
)

print(response.uuid)  # Session UUID
print(response.link)  # Payment link for customer

2. Subscription Session

Create Subscription Session

Copy

Create a session for recurring billing

PythonGoTypeScript

response = client.subscriptions.create_session(
	product_id=1,
	frequency=Duration(value=1, unit="months"),  # Bill monthly
	trial_period=Duration(value=7, unit="days"),  # 7-day trial (optional)
	min_periods=3,  # Minimum billing periods (optional)
	webhook_url="https://your-domain.com/webhook",
	customer_uuid="customer-uuid",
)

print(response.link)  # Send to customer

3. Pay-As-You-Go Session

Create Pay-As-You-Go Session

Copy

Create a session for usage-based billing

PythonGoTypeScript

response = client.pay_as_you_go.create_session(
	product_id=1,
	frequency=Duration(value=1, unit="months"),  # Bill monthly
	free_credits=100,  # Initial free credits (optional)
	webhook_url="https://your-domain.com/webhook",
	customer_uuid="customer-uuid",
)

print(response.link)

URL Placeholders

Customer UUID (Optional)

Session Expiration

Retrieving Session Details

Get Session Information

Copy

Fetch details about a session checkout

PythonGoTypeScript

session = client.one_time_payments.get_session("session-uuid")
print(session.product_name, session.price)

Monitoring Transactions

QBitFlow provides three ways to monitor transaction status: webhooks, success URLs, and WebSocket connections. Choose the method that best fits your use case.

Overview

Method 1: Webhooks (Recommended)

Setting Up Webhook Handler

Webhook Handler Implementation

Copy

Handle webhook notifications from QBitFlow

PythonGoTypeScript

from fastapi import FastAPI
from qbitflow import QBitFlow
from qbitflow.dto.transaction.session import SessionWebhookResponse
from qbitflow.dto.transaction.status import TransactionStatusValue

app = FastAPI()
client = QBitFlow(api_key="your_api_key")

@app.post("/webhook")
def handle_webhook(
	request: Request,
    x_webhook_signature_256: Annotated[str, Header()],
    x_webhook_timestamp: Annotated[str, Header()]
):
	"""Handle webhook events from QBitFlow."""

	# Read raw request body for signature verification
    body = await request.body()

    # Verify the authenticity of the webhook request
    if not qbitflow_client.webhooks.verify(
        payload=body,
        signature=x_webhook_signature_256,
        timestamp=x_webhook_timestamp
    ):
        print("❌ Invalid webhook signature")
        raise HTTPException(status_code=401, detail="Invalid webhook signature")
    
    # Parse payload after verification
    try:
        event = SessionWebhookResponse.model_validate_json(body)
    except ValidationError as e:
        print(f"❌ Failed to parse webhook payload: {e}")
        raise HTTPException(status_code=401, detail="Invalid webhook payload")
    
    # Extract event details
    session_uuid = event.uuid
    transaction_status = event.status.status
    transaction_type = event.status.type
    session = event.session
    
    print(f"Session UUID: {session_uuid}")
    print(f"Transaction Type: {transaction_type.value}")
    print(f"Transaction Status: {transaction_status.value}")
    print(f"Product: {session.product_name}")
    print(f"Price: {session.price} USD")
    print(f"Customer UUID: {session.customer_uuid}")
    
    # Handle different transaction statuses
    # ... your business logic here ...
    
    print("=" * 60)
    
    # Always return 200 OK to acknowledge receipt
    return {
        "status": "received",
        "session_uuid": session_uuid,
        "transaction_status": transaction_status.value
    }

⚠️ Important: Always return a 200 status code to acknowledge webhook receipt. If QBitFlow doesn't receive a 200 response, it will retry the webhook delivery multiple times.

Method 2: Success & Cancel URLs

Creating Session with URLs

Include Success/Cancel URLs

Copy

Add redirect URLs when creating sessions

PythonGoTypeScript

response = client.one_time_payments.create_session(
    product_id=1,
    success_url=f"{MY_URL}/success?uuid={{{{UUID}}}}&transactionType={{{{TRANSACTION_TYPE}}}}",
    cancel_url=f"{MY_URL}/cancel",
    customer_uuid="customer-uuid",
)

print(f"✓ Payment session created with redirects!")
print(f"  - Session UUID: {response.uuid}")
print(f"  - Payment Link: {response.link}")

Handling Success Redirect

Success URL Handler

Copy

Handle customers redirected after successful payment

PythonGoTypeScript

@app.get("/success")
async def handle_success(uuid: str, transactionType: TransactionType):
    """
    Handle success redirect from QBitFlow payment page.
    
    This endpoint is called when a customer completes a payment
    and is redirected back to your application.
    
    Args:
        uuid: The session or transaction UUID
        transactionType: The type of transaction (payment, subscription, etc.)
    
    Returns:
        Success page data or redirect
    """
    print("=" * 60)
    print("✅ Success redirect received")
    print("=" * 60)
    
    print(f"UUID: {uuid}")
    print(f"Transaction Type: {transactionType.value}")
    
    try:
        # Fetch the current transaction status
        transaction_status = qbitflow_client.transaction_status.get(
            transaction_uuid=uuid,
            transaction_type=transactionType
        )
        
        print(f"Current Status: {transaction_status.status.value}")
        
        # Handle different statuses
		# ... your business logic here ...
    
    except Exception as e:
        print(f"
❌ Error fetching transaction status: {e}")
        raise HTTPException(
            status_code=500,
            detail=f"Error processing success redirect: {str(e)}"
        )

Method 3: WebSocket (Real-Time)

WebSocket Monitoring

Copy

Monitor transaction status in real-time

PythonGoTypeScript

# Note: WebSocket support varies by SDK
# Check your SDK documentation for WebSocket implementation

# Most applications should use webhooks instead
# WebSockets are best for real-time UI updates

⚠️ Note: WebSockets are best used for real-time UI updates (like progress bars or status indicators). For reliable transaction processing, always implement webhook handlers as your primary monitoring method.

Best Practices

Managing Subscriptions

QBitFlow supports two types of subscription models: fixed recurring subscriptions and pay-as-you-go (PAYG) subscriptions. Both leverage smart contracts for automated, trustless billing.

Subscription Types

Creating Subscriptions

Step-by-Step Process

1. 1

   Create a Subscription Session

   Use the SDK or API to create a subscription session checkout with your desired parameters (frequency, trial period, etc.)

2. 2

   Share the Checkout Link

   Send the generated checkout link to your customer

3. 3

   Customer Completes Setup

   Customer visits the link, selects their cryptocurrency, and signs the allowance transaction

4. 4

   Monitor via Webhook or Success URL

   Receive notification when the subscription is successfully created

5. 5

   Fetch Subscription Status Regularly

   Poll the subscription status (e.g., once per day) to monitor billing cycles and handle status changes

Creating a Fixed Subscription

Create Recurring Subscription

Copy

Set up a monthly subscription with a 7-day trial

PythonGoTypeScript

response = client.subscriptions.create_session(
	product_id=1,
	frequency=Duration(value=1, unit="months"),  # Bill monthly
	trial_period=Duration(value=7, unit="days"),  # 7-day trial (optional)
	min_periods=3,  # Minimum billing periods (optional)
	webhook_url="https://your-domain.com/webhook",
	customer_uuid="customer-uuid",
)

print(response.link)  # Send to customer

Creating a Pay-As-You-Go Subscription

Create PAYG Subscription

Copy

Set up usage-based billing with monthly billing cycles

PythonGoTypeScript

response = client.pay_as_you_go.create_session(
	product_id=1,
	frequency=Duration(value=1, unit="months"),  # Bill monthly
	free_credits=100,  # Initial free credits (optional)
	webhook_url="https://your-domain.com/webhook",
	customer_uuid="customer-uuid",
)

print(response.link)

Monitoring Subscriptions

Fetch Subscription Status

Copy

Check subscription status and handle different states

PythonGoTypeScript

subscription = client.subscriptions.get("subscription-uuid")
print(subscription.status, subscription.next_billing_date)

# Handle different statuses
# ... your business logic here ...

Customer Self-Service Management

Available Customer Actions

Transaction Statuses

Understanding transaction statuses is crucial for properly handling payments and subscriptions in your application.

Status Values

Transactions go through various states during their lifecycle. Here are all possible transaction statuses:

Transaction Types

Transaction statuses apply to different types of transactions:

Checking Transaction Status

Get Transaction Status

Copy

Query the current status of any transaction

PythonGoTypeScript

# Check status of a one-time payment
status = client.transaction_status.get(
    transaction_uuid="transaction-uuid",
    transaction_type=TransactionType.ONE_TIME_PAYMENT
)

print(f"Type: {status.type.value}")
print(f"Status: {status.status.value}")

# Handle different statuses
# ... your business logic here ...

Subscription Statuses

Subscriptions have their own set of statuses that indicate the health and state of recurring billing. Understanding these statuses helps you provide the best service to your customers.

Status Overview

Status Transitions

Recommended Monitoring Strategy

Allowances, Max Amount & Pricing

Understanding how allowances, max amounts, and pricing work in QBitFlow is essential for managing subscriptions effectively.

What is an Allowance?

MaxSpending, MaxAmount & Num Periods Explained

Understanding these three concepts is crucial for properly managing subscriptions and controlling costs.

Comparison: When to Use What

What is Max Amount?

Pricing in USD

Best Practices

Network Fees & Gasless Transactions

Understanding who pays network fees for different transaction types and how QBitFlow's gasless transaction model works.

Gasless Transaction Model

Network Fees by Transaction Type

Here's a comprehensive breakdown of who pays network fees for each transaction type in QBitFlow:

Quick Reference Table

Benefits of the Gasless Model

Test Mode: Try Before You Go Live

Before accepting real payments, you can test the entire QBitFlow payment flow for free using test networks. No real money involved—just safe, risk-free experimentation.

Mainnet vs. Testnet

How to Use Test Mode

Test Your Integration

Learn how to test your QBitFlow integration safely using test networks before going live with real transactions.

Step-by-Step Testing Guide

1. 1

   Create Test API Key

   Create a Test API Key from the QBitFlow dashboard. This ensures that all transactions use test networks and no real funds are involved.

   How to Create Test API Key:

   1. 1.Log in to your QBitFlow dashboard
   2. 2.Navigate to Settings → API Keys
   3. 4.Create a new API Key, and select "Test" mode
   4. 5.Copy and securely store the key

   Test keys only work with test networks

   Any transactions created with test API keys will automatically use test networks (testnet), ensuring no real money is spent.

2. 2

   Set Up Test Wallets

   You need two wallets to simulate real-world transactions: one for the merchant (you) and one for the customer.

   Required Wallets:

   Merchant

   Your Wallet (Receives Payments)

   Set up a wallet on each test network you want to support. This wallet will receive test payments.

   Customer

   Test Customer Wallet (Sends Payments)

   Create a separate wallet to simulate customer behavior and test the payment flow.

   💡 Wallet Recommendation:

   For Ethereum testnets: Use MetaMask or any Web3 wallet
   For Solana testnets: Use Phantom or Solflare

3. 3

   Fund Test Wallets with Faucets

   Use test network faucets to get free test tokens. You'll need tokens for each currency you want to support.

   Ethereum Test Networks

   Sepolia Testnet (Recommended)

   • •
     Faucet: sepoliafaucet.com
   • •
     Alternative: Alchemy Faucet
   • •
     Alternative: Google Faucet

   Solana Test Networks

   Devnet

   • •
     Faucet: faucet.solana.com
   • •
     CLI: solana airdrop 2

   Test tokens

   Get test USDC on Circle (Sepolia or Solana Devnet)

   Faucet: faucet.circle.com

   🌐 More Networks Coming Soon

   QBitFlow is constantly adding support for more blockchain networks. Check the dashboard for the latest supported test networks.

4. 4

   Configure Test Merchant Wallets

   Add your merchant test wallets to the QBitFlow dashboard so you can receive test payments.

   Steps:

   1. 1.Go to QBitFlow dashboard → Wallets
   2. 2.Toggle to "Test Mode" environment
   3. 4.For each currency you want to support, add a wallet:
   4. •Select the test network (e.g., Ethereum Sepolia)
   5. •Enter your wallet's public address
   6. •Click "Add Wallet"

   Easy Currency Support

   Supporting a new currency is simple: just add a wallet for that currency in the dashboard. For native currencies, add the wallet directly. For tokens, wallets are automatically handled from your main wallet and initialized if needed.

5. 5

   Simulate Transactions

   Test all transaction types using your test API key and test wallets.

   Test Scenarios:

   One-Time Payments

   Create a payment session and complete the payment flow with your test customer wallet.

   Create Subscription

   Set up a recurring subscription and verify the allowance approval process.

   Subscription Billing

   Test automatic billing cycles and status changes.

   Cancel Subscription

   Verify that cancellations work correctly and are free for users.

   PAYG Subscriptions

   Test pay-as-you-go billing with usage tracking.

   Increase Allowance

   Test the flow when customers need to increase their subscription allowance.

   Update Max Amount

   Test max amount updates when crypto prices fluctuate.

6. 6

   Test Webhooks & URLs

   Verify that your webhook endpoints and success URLs are working correctly.

   Testing Webhooks Locally:

   • •Use ngrok or similar tools to expose your local server: ngrok http 3000
   • •Use the ngrok URL as your webhook endpoint
   • •Monitor webhook requests in real-time

Going Live: Production Checklist

Adding New Currencies

Best Practices & Advanced Topics

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

Security Best Practices

Environment Variables Example

Secure API Key Storage

Copy

PythonGoTypeScript

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

Comprehensive Error Handling

Copy

PythonGoTypeScript

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

-- 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

Performance Optimization

Production Checklist

Monitoring & Analytics