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.
Building a marketplace? See how crypto payouts for marketplaces work →
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 the endpoint you configured in the dashboard with the transaction details. This happens regardless of whether the customer closes their browser or loses internet connection.
See the Webhooks section
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.
New to on-chain subscriptions? See how recurring crypto payments work →
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
Subscription status webhook (recommended)
Subscriptions are long-lived, so their status changes over time (billing succeeds, allowance runs low, billing fails, the subscription is cancelled). Configure the Subscription status webhook in the dashboard to be notified the instant a transition happens — no cron required.
Set it up
Polling (optional fallback)
You can also fetch a subscription's status directly at any time — useful as a fallback or to reconcile your records. This is optional now that the status webhook exists.
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 billing history, perform actions like canceling, increasing allowance, or updating the max amount, and request a refund on a specific billing. All actions require wallet signature verification for security — QBitFlow builds and hosts this whole management surface, so you don't have to.
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.
View billing history
Customers see every charge on the subscription, each with its transaction hash and a link to view the payment on a block explorer — fully verifiable on-chain.
Request a refund
Customers can raise a refund request for a specific billing directly from the management page. You review and action it from your dashboard.
Automation tip
Webhooks
Webhooks are the most reliable way to react to what happens in QBitFlow. You configure your endpoints once in the dashboard, and QBitFlow sends a signed POST request to them whenever a relevant event occurs.
Configure endpoints in the dashboard
Settings → Webhooks
Webhook URLs are no longer set per session. Go to Settings → Webhooks and set your endpoints there. Test and Live keep separate configurations: test-mode events are delivered to your Test endpoints, and live-mode events to your Live endpoints.
Two independent webhooks
Transaction webhook
Individual payment events
Fires on individual payment events — a payment completes, or a new subscription is created. Use it to record payments and unlock access the moment funds move. The payload is a SessionWebhookResponse containing the session details and the transaction status.
Handling the transaction webhook
Subscription status webhook
Subscription lifecycle events
Fires whenever an existing subscription changes state — e.g. active → low_on_funds, active → past_due, or past_due → cancelled. Get notified the instant a status changes instead of polling for it on a cron.
Payload fields
subscriptionUUID— the subscription that changed.subscriptionReference(Optional) — your own reference to the subscription that changed.previousStatus— the status it moved from.currentStatus— the status it moved to.updatedAt— when the transition happened.
Handling the subscription status webhook
No more polling
Verifying webhooks
Always verify the signature
Every delivery includes the headers X-Webhook-Signature-256, X-Webhook-Timestamp, and X-Webhook-ID. Verify the signature before trusting a payload — the SDKs expose a webhooks.verify(payload, signature, timestamp) helper for this.
Use the raw request body
Testing your endpoint
The "Test the endpoint" action
In Settings → Webhooks, the “Test the endpoint” button sends a probe request to the URL you entered so you can confirm it is reachable. The probe carries a fake payload that is not a real event.
Short-circuit the test probe
X-Webhook-ID header set to TEST_WEBHOOK_ID ("test-webhook-id"). When it matches, return HTTP 200 immediately and skip normal payload processing — otherwise your handler may fail to parse the fake payload. The SDKs expose this constant and header for you (see the handlers above).Always return 200
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.
Subscribe to the status webhook
Configure the Subscription status webhook in the dashboard. Its payload includes the previous and current status, so you know exactly what changed.
- 2.
React on transition
Trigger actions directly from the webhook — the transition is delivered to you, so there's no need to diff against a stored status.
- 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.
- 6.
Polling as a fallback
Optionally reconcile with a periodic status fetch to catch anything missed — no longer the primary mechanism.
Pro tip
Marketplace payouts & seller onboarding
Run a marketplace and QBitFlow pays your sellers for you. You onboard a seller, they get paid, and your platform fee is taken automatically — without you ever becoming the bank. This is the full lifecycle of a seller account, from creation to self-custody.
How a marketplace is structured
Organization
Your marketplace — created when you sign up
Seller A
own wallet
Seller B
own wallet
Seller C
own wallet
A marketplace is an organization with your sellers as users underneath it. You onboard them and take your cut; each seller has their own revenue stream and their own wallet.
The account lifecycle
Seller created
You create the seller in one API call. No signup needed from them.
Unclaimed
They can be paid immediately. Earnings land in your org wallets; QBitFlow tracks the ledger.
Claim request
You generate a claim link and send it to the seller.
Claimed
Seller sets their password and connects their own wallets.
Settlement
You send the tracked balance in one signature. Amount pre-filled from the ledger.
On-chain
Future payments go straight to the seller's own wallet, non-custodially.
Instant path: create the claim request at the same time as the seller and skip straight to On-chain — no unclaimed balance, no settlement step.
Step by step
- 1
Your organization is created on signup
When you sign up, an organization is created automatically with you as the owner, and you set up your organization wallets. This is your platform's home base — where unclaimed sellers' earnings are received.
- 2
Create sellers via the SDK or API
With one call you create a user-level account for a seller. From that moment they can already receive payments — you don't have to wait for them to sign up.
Create a sellerRequires an organization-level API key (admin only). - 3
Sellers earn immediately, into a tracked balance
Until a seller claims their account, it is unclaimed: they can be paid, but they don't have access to the account yet. Those payments are received into your organization wallets, and QBitFlow keeps a precise ledger of exactly how much is owed to each unclaimed seller. Nothing is lost or ambiguous — every cent is tracked and reviewable.
- 4
Claim an account when you're ready to onboard the seller
Create a claim request for that seller. QBitFlow returns a link — you send it to the seller, who sets their password and their wallets. From then on they have full access to their own account.
Create a claim requestAlso uses your organization-level API key. - 5
Settle what they earned — once, with one signature
When a seller claims their account, QBitFlow creates a claim-fund entry for you. Your dashboard lists every claimed account waiting to be settled, with the exact amount already filled in from the ledger QBitFlow kept while the account was unclaimed. You review it — the full ledger entries are there if you want to verify every line — then sign one transaction to send the funds. That's it.
- 6
After that, it's hands-off and non-custodial
Once settled, that seller is fully on-chain like any other. Their future payments go straight to their own wallet, your platform fee is taken automatically each time, and you have nothing left to do — you just receive your share whenever they get paid.
The two-sided trust layer — why it matters
Steps 3–5 are the trust layer. It solves a genuine tension every marketplace feels.
Sellers: zero onboarding friction
A new seller can list, sell, and start earning before they've signed up for anything. You don't lose them to a signup wall at the exact moment they're deciding whether your marketplace is worth the effort.
You: commit only once they're worth it
You're not pushing funds to strangers. A seller's earnings accrue in a tracked ledger, and you only create the claim request — and settle their funds — once they've proven real and trustworthy. If someone never pans out, you were never on the hook.
Who holds the money?
QBitFlow never holds funds. While an account is unclaimed, the marketplace temporarily holds that seller's earnings in its own organization wallets, and QBitFlow keeps only the ledger recording what's owed. Once the seller claims and you settle — or from the first sale, if you onboard them on-chain immediately — every payment goes straight to the seller's own wallet. The smart contracts are open-source and auditable, so neither side has to take our word for any of it.
Fees: two separate things
QBitFlow's fee
A flat 1.5% on every transaction. This is QBitFlow's only charge — no setup, monthly, or withdrawal fees.
Your platform fee
A separate percentage you charge your sellers, set per seller (organizationFeeBps, in basis points). It's deducted automatically on top of QBitFlow's 1.5% and routed to your organization.
The two are always kept distinct: QBitFlow's flat 1.5% is never your platform fee, and your platform fee is entirely yours to set.
Which API key to use
- The API key authenticates as its owner. Create sellers and claim requests with your organization-level API key.
- To actually get a seller paid, create the checkout session with that seller's user API key — this creates a session checkout for the seller, so funds (and your platform fee) route correctly.
Prefer no trust layer? Onboard instantly.
The trust layer is optional. To bring a seller fully on-chain from the start — no held balance, no settlement step — simply create the claim request at the same time you create the seller. They set up their account in a few steps and are immediately live and self-custodial.
No claim-fund to settle, no signature, no funds for you to send later — every payment goes straight to the seller's own wallet from their very first sale. Pick this when you already trust the seller; pick the trust layer when you want to let them earn first and commit later.
See it end to end
Prefer the plain-English version? The marketplace overview walks through the same flow from both the marketplace's and the seller's point of view.
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!