QBitFlow docs.
Everything you need to integrate crypto payments — from your first checkout to going live.
Welcome to QBitFlow
QBitFlow is a non-custodial cryptocurrency payment platform. It supports one-time payments and recurring subscriptions via session checkout links — hosted pages where customers pay in crypto. Funds go directly to your wallet; QBitFlow never holds them. Webhooks notify your server of payment events in real time.
Key features
Quick start
Getting started
Follow these steps to integrate QBitFlow into your application and start accepting cryptocurrency payments.
Create account
Set up your QBitFlow merchant account
Add wallet
Pick a chain and sign with your wallet
Create product
Define what you're selling
Test it
Preview & try your payment page
You're set
Start accepting crypto payments
Quick start guide
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
🎉 Congratulations!
Next steps
📚 Learn about organization structure
Understand how roles, permissions, and user management work in QBitFlow.
🔔 Set up webhooks
Learn how to receive real-time notifications when payments are completed.
🔄 Create subscriptions
Set up recurring billing with flexible subscription plans.
⚙️ Explore advanced features
Discover customer management, accounting exports, and more.
Organization structure & roles
Understanding how organizations, users, and roles work in QBitFlow is essential for effective team collaboration and payment management.
Organization hierarchy
Organization
Every user belongs to an organization. When you sign up, an organization is automatically created with you as the owner. An organization can have multiple members with different roles and permissions.
User roles
QBitFlow has three distinct user roles, each with different permissions and capabilities:
Owner
The owner has complete control over the organization and all its resources.
Permissions:
- Full access to all organization resources
- Manage organization settings and billing
- Add, remove, and manage all users
- Access organization-level wallets and revenue
- Transfer ownership to another user
Admin
Admins have nearly the same privileges as the owner and operate at the organization level.
Permissions:
- Access organization-level wallets and shared revenue
- Create and manage products
- Manage customers and view all transactions
- Generate and manage API keys
- Cannot transfer ownership or delete the organization
User
Users operate independently within the organization with their own wallets and revenue streams.
Permissions:
- Receive payments to their own wallet (separate from organization)
- Create products and manage their own inventory
- View only their own transactions and customers
- Subject to organization fee (if configured)
- Cannot access organization-level resources
Organization-level vs user-level
Organization-level (owner & admins)
Revenue sharing
All payments go to shared organization wallets. Revenue is pooled and accessible by owners and admins.
Use case
Best for businesses where the organization handles all billing and revenue management.
Example
A SaaS company where all subscriptions are managed centrally by the business.
User-level (users)
Independent revenue
Payments go directly to user's individual wallet. Each user manages their own revenue.
Use case
Perfect for marketplaces where individual sellers or service providers need to receive payments.
Example
An online marketplace where each vendor receives payments for their own products.
Organization fees for users
Revenue sharing model
Organizations can configure a fee percentage that is automatically deducted from user-level payments. This lets marketplace owners generate revenue while enabling individual users to accept payments.
Example
If a marketplace sets a 5% organization fee:
- Customer pays $100 for a product from User A
- QBitFlow receives the 1.5% fees ($1.50)
- Organization receives 5% as the platform fee (5% of (100 − 1.5) = $4.925)
- User A receives $93.575 in their wallet
API keys and permissions
Using API keys
When making API requests, the API key determines the scope and permissions:
Organization-level API key (owner/admin)
User-level API key
Choosing the right structure
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?
Payment session
A session checkout is a payment session initialized with a unique link that you share with your customer. When a customer wants to make a payment (one-time or subscription), you create a new session checkout and provide them with the link. The customer then visits this link to complete the payment in their preferred cryptocurrency.
Creating session checkouts
You can create session checkouts for different types of payments:
1. One-time payment session
2. Subscription session
URL placeholders
When creating session checkouts, you can use placeholders in your success and cancel URLs. These are automatically replaced by QBitFlow when redirecting the customer:
{{UUID}}Replaced with the session UUID. Use this to identify the payment/subscription in your success handler.
{{TRANSACTION_TYPE}}Replaced with the transaction type (e.g., "payment", "createSubscription").
Example URL
https://yoursite.com/success?uuid={{UUID}}&type={{TRANSACTION_TYPE}}Becomes: https://yoursite.com/success?uuid=01997c89-d0e9-7c9a-9886-fe7709919695&type=payment
Customer UUID (optional)
When creating a session checkout, you can optionally provide a customerUUID:
✅ With customer UUID
If you provide a customer UUID (matching an existing customer in your QBitFlow account), the payment is automatically associated with that customer. The customer won't need to fill in their information again.
📝 Without customer UUID
If you don't provide a customer UUID, the customer is asked to fill in their information (name, email, etc.) during checkout. A new customer record is created automatically if they don't already exist.
Session expiration
Time limit
Session checkout links expire after a certain period (typically 24 hours). After expiration, the link will no longer be valid, and you'll need to create a new session for the customer. The expiration timestamp is included in the session creation response.
Retrieving session details
Best practice
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
Webhooks
Server-to-server notifications. Most reliable method for production use.
Success URLs
Redirect customers after payment. Great for immediate user feedback.
WebSocket
Real-time status updates. Use when immediate feedback is critical.
Method 1: Webhooks (recommended)
Reliable server-to-server notifications
Webhooks are the most reliable way to receive payment notifications. When a transaction is processed, QBitFlow sends a POST request to your webhook URL with the transaction details. This happens regardless of whether the customer closes their browser or loses internet connection.
Setting up webhook handler
Important
Method 2: Success & cancel URLs
Redirect-based monitoring
Success and cancel URLs provide immediate feedback to your customers by redirecting them back to your site after they complete or cancel a payment. While not as reliable as webhooks (customers might close their browser), they're excellent for providing instant user feedback.
Creating session with URLs
Handling success redirect
Method 3: WebSocket (real-time)
Real-time status updates
WebSocket connections provide real-time transaction status updates. This is useful when you need immediate feedback, but it's generally not recommended as the primary monitoring method since it requires maintaining an active connection. Use WebSockets for UI updates while relying on webhooks for business logic.
Note
Best practices
Use webhooks as primary method
Always implement webhook handlers for production. They're the most reliable way to receive payment notifications, working even if customers close their browser.
Combine webhooks with success URLs
Use webhooks for reliable server-side processing and success URLs for immediate customer feedback. This combination provides the best user experience.
Always return 200 for webhooks
Your webhook endpoint must return HTTP 200 to acknowledge receipt. If QBitFlow doesn't receive a 200 response, it will retry delivery.
Verify transaction status
In success URL handlers, always verify the transaction status by querying the API. Don't trust the redirect alone for critical business logic.
Use WebSockets for UI only
WebSockets are perfect for real-time UI updates (progress bars, status badges), but rely on webhooks for actual payment processing logic.
Managing subscriptions
QBitFlow supports fixed recurring subscriptions powered by smart contracts for automated, trustless billing.
Subscription types
Fixed recurring subscriptions
Traditional subscription model with fixed amounts charged at regular intervals (weekly, monthly, yearly).
Creating subscriptions
Step-by-step process
- 1
- 2
- 3
- 4
- 5
Creating a fixed subscription
Monitoring subscriptions
Regular status polling
Unlike one-time payments that complete immediately, subscriptions are long-lived. You should fetch the subscription status regularly (e.g., once per day using a cron job) to monitor billing cycles, detect status changes, and take appropriate actions.
Customer self-service management
Public management page
QBitFlow provides a public subscription management page that customers can access without logging in. Customers can view their subscription details and perform actions like canceling, increasing allowance, or updating the max amount. All actions require wallet signature verification for security.
Management page URL:
https://qbitflow.app/user/<ref-id>/manage?uuid=<subscription-uuid>Share this link with your customers so they can manage their subscriptions themselves. Reduces support overhead and empowers customers.
Available customer actions
Cancel subscription
Customers can cancel their subscription at any time. Requires wallet signature to verify ownership.
Increase allowance
If the subscription shows "low_on_funds" status, customers can increase their allowance to ensure future billings succeed.
Update max amount
If crypto prices drop and the max amount is reached, customers can update it to resume billing.
Automation tip
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:
created
The transaction has been created and acknowledged by the backend. It's being prepared to be sent to the blockchain.
waitingConfirmation
The transaction has been sent to the blockchain and is waiting for confirmations. This is a normal state during blockchain processing.
pending
The transaction is pending additional processing or actions. Continue monitoring until status changes.
completed
The transaction has been successfully completed and confirmed on the blockchain. This is a final, successful state.
failed
The transaction has failed. This could be due to insufficient funds, network issues, or other errors. This is a final state.
expired
The transaction couldn't be processed within the time limit and has expired. A new transaction needs to be created.
cancelled
An error occurred and the transaction was cancelled. It was not processed successfully.
Transaction types
Transaction statuses apply to different types of transactions:
paymentOne-time payment transaction.
createSubscriptionCreating a new subscription.
cancelSubscriptionCancelling an existing subscription.
executeSubscriptionExecuting a subscription billing cycle.
increaseAllowanceIncreasing subscription allowance.
updateMaxAmountUpdating subscription max amount.
Checking transaction status
Best practice
Subscription statuses
Subscriptions have their own set of statuses that indicate the health and state of recurring billing. Understanding these helps you provide the best service to your customers.
Status overview
active
The subscription is active and functioning normally. Billing cycles are executing successfully, and the customer has sufficient allowance.
Action required
past_due
The last billing cycle failed. QBitFlow will automatically retry the billing. After a grace period, if billing still fails, the subscription will be cancelled.
Action required
low_on_funds
The last billing cycle succeeded, but the customer's allowance is running low. The next billing cycle might fail if they don't increase their allowance.
Action required
pending
The max amount limit has been reached for this billing cycle. This typically happens when cryptocurrency prices drop significantly. The customer must update their max amount before billing can proceed.
Action required
cancelled
The subscription has been cancelled either by the customer or automatically due to billing failures after the grace period. This is a final state.
Action required
trial
The subscription is in its trial period. No billing occurs during this time. When trial ends, it automatically transitions to "trial_expired".
Action required
trial_expired
The trial period has ended but the customer hasn't upgraded. They can upgrade via the subscription management page. After grace period, will be cancelled.
Action required
Status transitions
Normal flow
Warning states
Billing issues
Max amount issues
Trial expiration
Recommended monitoring strategy
- 1.
Daily status check
Set up a cron job that runs once daily to fetch all active subscriptions and check their status.
- 2.
Status change detection
Compare current status with previous status. If changed, trigger appropriate actions.
- 3.
Automated notifications
Send emails when status becomes "low_on_funds", "pending", or "trial_expired". Include link to management page.
- 4.
Access control
Grant/revoke service access based on status. "active" and "trial" = full access. "cancelled" = no access.
- 5.
Grace period handling
For "past_due" and "pending" states, consider maintaining limited access during grace period while notifying customer.
Pro tip
Allowances, max amount & pricing
Understanding how allowances, max amounts, and pricing work in QBitFlow is essential for managing subscriptions effectively.
What is an allowance?
Authorized amount, not escrow
An allowance is the amount a customer authorizes QBitFlow smart contracts to pull from their wallet for subscription billing. This is NOT an escrow — the customer keeps their funds in their wallet. They simply authorize the smart contract to pull up to this amount over time.
How allowances work
When creating a subscription, the customer selects how many billing periods they want to authorize (e.g., 3 months, 6 months, 12 months).
The required allowance is calculated automatically:
price × periods × (1 + buffer)The customer signs one transaction to approve this allowance.
On each billing cycle, the smart contract automatically pulls the exact amount due.
The allowance decreases with each billing but funds remain in customer's wallet until billed.
Allowance safety
Allowances are safe and controlled
- ✓Billing frequency (can't bill more often than agreed)
- ✓Exact amount per billing cycle (can't exceed agreed price)
- ✓Customer can cancel anytime to stop future billings
- ✓All rules are enforced on-chain and verifiable
Example allowance calculation
* Includes buffer for price fluctuations
MaxAmount & num periods explained
Understanding these concepts is crucial for properly managing subscriptions and controlling costs.
MaxAmount (all subscriptions)
Definition: Used to handle price fluctuations in cryptocurrency values, ensuring individual payments don't exceed a reasonable threshold.
For regular subscriptions
- •Set as a percentage of subscription price at creation time
- •Accommodates reasonable price changes in crypto markets
- •Can be updated later if needed
Example
For a $100/month subscription, MaxAmount might be set to 120 USDC (20% buffer). If the price of USDC drops and would require 130 USDC (equivalent to $100 at the time of payment), the transaction will be blocked until the user updates MaxAmount, protecting them from excessive charges.
USDC is designed to be stable and closely match the USD value, so the amount of USDC needed for a $100 subscription should remain consistent. However, for other tokens/native currencies like ETH or SOL, prices can fluctuate significantly. MaxAmount acts as a safeguard to prevent unintended or unexpectedly large charges if the token price drops.
Num periods (subscription creation)
Definition: Used when creating subscriptions to automatically compute and set the allowance based on the subscription price and number of periods specified.
Purpose
- •Streamlines subscription setup by pre-calculating allowance
- •Defines how many billing cycles the customer authorizes upfront
- •Reduces friction — users don't manually calculate required allowance
How it works
Allowance = Price × NumPeriods × (1 + Buffer)
If subscription is $99.99/month and user selects 6 periods, the system automatically calculates the required allowance (≈ $620 with buffer) and prompts the user to approve it.
Comparison: when to use what
| Concept | Used for | Purpose | Who sets it |
|---|---|---|---|
| MaxAmount | All subscriptions | Handle crypto price volatility | System (with buffer) |
| Num periods | Subscription creation | Calculate initial allowance | User/customer |
Pricing in USD
Stable pricing for merchants
All product prices in QBitFlow are set in USD. When a customer pays, QBitFlow automatically converts the USD price to the customer's selected cryptocurrency at the current exchange rate. This gives you predictable revenue while customers can pay in their preferred crypto.
How price conversion works
You set USD price
Create a product with price: $99.99
Customer selects cryptocurrency
Customer chooses to pay in ETH, USDC, SOL, etc.
Automatic conversion
QBitFlow fetches the current exchange rate and calculates the equivalent amount in the selected crypto.
Customer pays
Customer pays the converted amount in their chosen cryptocurrency.
Key takeaway
Network fees & gasless transactions
Understanding who pays network fees for different transaction types and how QBitFlow's gasless transaction model works.
Gasless transaction model
Seamless user experience
When payments are made in tokens, QBitFlow implements a gasless transaction model where users don't pay network fees directly. QBitFlow covers these fees on behalf of users for a seamless experience.
How it works
Users don't need native currency
Users don't need to hold the native cryptocurrency of the blockchain (like ETH for Ethereum or SOL for Solana).
QBitFlow pays gas fees upfront
QBitFlow pays gas fees with the native currency and is refunded in tokens as part of the transaction process.
Fees paid only on success
Fees are paid by the user only when a transaction is successfully executed. Failed transactions don't cost the user anything.
Why some actions require gas
QBitFlow uses smart contracts, and each important action is performed on-chain. Even if funds aren't moved (for example, creating a subscription), the action still updates contract state and therefore requires a network fee. Doing these critical updates on-chain ensures security, auditability, and transparency.
Our smart contracts are optimized to minimize network fees. QBitFlow follows an off-chain-first policy to reduce costs, performing as much computation and validation off-chain as possible. However, actions that impact security or user funds must be finalized on-chain and will require gas.
Network fees by transaction type
Here's a comprehensive breakdown of who pays network fees for each transaction type in QBitFlow:
One-time payment
ONE_TIME_PAYMENTFor one-time payments, the user pays the network fees to process the transaction on the blockchain. When paying with tokens, this is handled seamlessly via QBitFlow's gasless model. When paying in the chain's native currency (e.g., ETH, SOL), the user pays gas directly; the gasless model does not apply.
Create subscription
CREATE_SUBSCRIPTIONWhen creating a new subscription, the user pays the network fees required to set up the allowance and initialize the subscription smart contract. Although no funds move at this step, it updates on-chain state for security and transparency.
Cancel subscription
CANCEL_SUBSCRIPTIONWhen canceling a subscription, QBitFlow covers the network fees. The user doesn't pay anything to cancel. The cancellation is recorded on-chain to ensure transparent and final state updates.
Execute subscription payment
EXECUTE_SUBSCRIPTION_PAYMENTWhen a subscription billing cycle is executed, the user pays the network fees. This is part of the automated recurring payment process and is finalized on-chain for accuracy and security.
Increase allowance
INCREASE_ALLOWANCEWhen increasing the allowance for a subscription, the user pays the network fees. This updates the smart contract state on-chain and is necessary for secure spending limits.
Update max amount
UPDATE_MAX_AMOUNTUpdating the max amount for a subscription requires the user to pay network fees. This modifies the subscription parameters on-chain to guarantee transparent enforcement.
Quick reference table
| Transaction type | Code | Who pays |
|---|---|---|
| One-time payment | payment | User |
| Create subscription | createSubscription | User |
| Cancel subscription | cancelSubscription | QBitFlow |
| Execute subscription | executeSubscription | User |
| Increase allowance | increaseAllowance | User |
| Update max amount | updateMaxAmount | User |
Key takeaway: gasless transactions
Benefits of the gasless model
Lower barrier to entry
Users don't need technical knowledge about blockchain gas fees or managing multiple cryptocurrencies.
Simplified user experience
One transaction, one currency — users pay in their chosen token without worrying about gas.
No failed transaction costs
If a transaction fails, users don't pay anything — they only pay when transactions succeed.
Free cancellations
Users can cancel subscriptions without any cost, removing barriers to trying your service.
Testing & going live
Before accepting real payments, test the entire QBitFlow payment flow for free using test networks. No real money involved — just safe, risk-free experimentation.
What is test mode?
Mainnet vs. testnet
Mainnet (live)
- 💰Real cryptocurrency & real money
- ✅Actual payments from customers
- 🔒Funds go directly to your wallets
Testnet (test)
- 🎮Fake cryptocurrency with zero value
- 🧪Test the full payment flow safely
- 🆓Get free test tokens from faucets
How to use test mode
Key terms explained
Test network (testnet)
A separate blockchain environment that works exactly like the real network, but uses fake cryptocurrency with zero real value. Perfect for testing.
Faucet
A free service that gives you test tokens. Think of it as a free dispenser — you paste your wallet address and claim free test crypto instantly.
Test tokens
Fake cryptocurrency used on test networks. They have zero real value and are only useful for testing. You can't sell or trade them.
Mainnet
The real blockchain network where actual cryptocurrency transactions happen. This is where real money changes hands.
Why test mode matters
- ✓Zero risk: No real money involved — experiment freely.
- ✓Full experience: Test the complete payment flow end-to-end.
- ✓Confidence: Know exactly how your customers will experience payments.
- ✓Integration testing: Verify your setup before going live.
Going live
Once you're confident with test mode, follow these steps to switch to mainnet and start accepting real payments.
Create production wallets for each currency you want to support. These will receive real payments.
Security first
- •Use hardware wallets or secure multi-sig setups.
- •Never share private keys or seed phrases.
- •Enable all available security features.
- •Backup your wallet securely.
Add your production wallet addresses to the QBitFlow dashboard in Live mode.
Steps
- 1.Switch dashboard to "Live mode".
- 2.Navigate to Settings → Wallets.
- 3.Add wallet for each supported currency.
One wallet per currency
Create a production API key and update your integration to use it.
Steps
- 1.Go to Settings → API Keys in Live mode.
- 2.Click "Generate new live API key".
- 3.Copy the key and store it securely.
- 4.Update your environment variables with the live key.
- 5.Deploy your application with the new key.
Never commit API keys
Ensure your production webhook endpoints are accessible and working correctly.
Checklist
- Webhook URL is publicly accessible (HTTPS)
- Signature verification is implemented
- Error handling is in place
- Webhook logs are being monitored
You're now ready to accept real cryptocurrency payments!
🎉 You're live!
- •Monitor the first few transactions closely.
- •Verify funds are being received correctly.
- •Check webhook notifications are working.
- •Keep test mode available for debugging.
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
Error handling
Always implement proper error handling to gracefully handle API failures, network issues, and validation errors.
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
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.
🎉 You're ready!