Finance
How to add crypto payments to any website in 10 minutes
QBitFlow Team
9 min read
On this page · 10 sections
Your client sends you a message: "Can we accept crypto on the site?"
Or maybe you're building a side project and you want to accept USDC instead of paying Stripe's 2.9% + $0.30 per transaction.
Either way, you Google it, and every guide you find is either a 45-minute deep dive into smart contract development or a marketing page that doesn't show you any actual code.
Here's the thing: adding crypto payments to a website is about as complicated as integrating any other payment API. Create a checkout session, redirect the customer, handle the webhook. That's it.
Let me show you how. Real code, working examples, 10 minutes.
What we're building
By the end of this tutorial, you'll have:
- A checkout flow that accepts crypto payments (ETH, USDC, SOL, and more)
- Webhook handling to fulfil orders when payments complete
- A working test environment to verify everything before going live
We're using QBitFlow, a non-custodial crypto payment API. "Non-custodial" means funds go directly from your customer's wallet to yours. QBitFlow never holds your money. The smart contracts are open-source, so you can read exactly what's happening on-chain.
Prerequisites
You need three things:
- A QBitFlow account. Sign up here with your email. It's free.
- A crypto wallet address on Ethereum, Base or Solana. Just the public address, plus a signed message proving it's yours. You're not handing over any private keys or seed phrases.
- Your preferred SDK. QBitFlow has official SDKs for TypeScript (JavaScript), Python, Go and PHP.
Step 1: install the SDK (2 minutes)
Pick your language:
Shell
# JavaScript / TypeScript (Node.js 20+)npm install qbitflow # Python (3.10+)pip install qbitflow # Gogo get github.com/QBitFlow/qbitflow-go-sdk/v3 # PHPcomposer require qbitflow/qbitflow-phpThen create an API key in the QBitFlow dashboard. Keys belong to a mode: create a test key while the dashboard is in test mode, and a live key in live mode when you're ready. Keep the key in an environment variable, never in code or in a browser.
Step 2: create your first payment (3 minutes)
Here's a complete Express.js example that creates a one-time payment and redirects your customer to QBitFlow's hosted checkout:
JavaScript
import express from 'express';import { Placeholders, QBitFlow } from 'qbitflow'; const app = express();const client = new QBitFlow( process. env. QBITFLOW_API_KEY ?? ''); app.post('/checkout', async (req, res) => { // An inline product: nothing needs to exist in your catalog. QBitFlow replaces {{UUID}} with // the session's id on the redirect. const session = await client. checkoutSessions. createPayment( { productName: 'Premium Plan', description: 'Awesome additional features', price: 4.99, // USD (test mode caps prices at $5) reference: 'order-1042', // your order id: unique per space successUrl: `https://yoursite.com/success?uuid=${Placeholders. UUID}`, cancelUrl: 'https://yoursite.com/cancel', }); // Redirect the customer to QBitFlow's hosted checkout page res.redirect(session.link);}); app.listen(3000);That's the entire checkout integration. Your customer clicks "Pay", lands on QBitFlow's hosted checkout, picks their chain and coin, connects their wallet and signs. Then they're sent back to your successUrl. They need no account.
You can brand the hosted checkout (your logo and colors) from the QBitFlow dashboard, so it doesn't feel like your customer left your site.
Python alternative
Same thing in Flask:
Python
import os import qbitflowfrom flask import Flask, redirect app = Flask(__name__)client = qbitflow. QBitFlow( os. environ["QBITFLOW_API_KEY"]) @app.route("/checkout", methods=["POST"])def checkout(): session = client. checkout_sessions. create_payment( product_name="Premium Plan", description="Awesome additional features", price=4.99, # USD reference="order-1042", # your order id: unique per space # QBitFlow replaces the placeholder with the session's id when it redirects the customer. success_url=f"https://yoursite.com/success?uuid={qbitflow. PLACEHOLDER_UUID}", cancel_url="https://yoursite.com/cancel", ) return redirect(session.link)Same flow, same result. The API is the same across SDKs: only the syntax changes.
Step 3: handle the webhook (3 minutes)
Redirecting to a success page isn't enough: your customer could just navigate to /success directly. You need server-side confirmation, and that's the webhook.
First, create a webhook endpoint in your dashboard (Settings → Webhooks) with your URL, and store its whsec_… signing secret: it's shown only once. QBitFlow then posts an event to that URL when something happens, like payment.completed. The SDK's router verifies the signature, parses the event and answers QBitFlow:
JavaScript
import express from 'express';import { webhooks } from 'qbitflow'; const router = webhooks . router( process. env. QBITFLOW_WEBHOOK_SECRET) .on('payment.completed', async (payment, event) => { // Confirmed on-chain: fulfil the order. Idempotent: deduplicate on event.id. await fulfilOrder(payment.reference, event.id); }) .on('checkout.expired', (session) => { // Never paid: release what the order holds. console.log('release order', session.reference); }); const app = express();// The raw body, before any express.json(): the router verifies the signature over it.app.post('/webhooks/qbitflow', express.raw({ type: 'application/json' }), router.nodeHandler());app.use(express.json()); // the rest of your API, after the webhook routeapp.listen(3000);A few things to note:
- The signature is checked for you. Each delivery carries a
QBitFlow-Signatureheader (a timestamp and an HMAC-SHA256 of the raw body). The router refuses a bad or stale one with a 400, and no handler runs. - Deliveries come at least once. The same event can arrive twice: deduplicate on
event.id. - A failed attempt isn't final. If your customer's first try fails, they can pay again from the same checkout. Release the order on
checkout.expired, never before. payment.explorerUrllinks to the transaction on the chain's block explorer, if you want to check it yourself.- Answer fast. The router answers 200 once your handlers return. If one throws, it answers 500 and QBitFlow retries later. Do heavy work (emails, reports) in the background.
Step 4: test it (2 minutes)
QBitFlow has a test mode, so you don't spend real crypto while developing.
- Use your test API key (created in the dashboard's test mode, separate from live)
- Pay on a test network: Sepolia, Base Sepolia or Solana Devnet
- Get free test tokens from the QBitFlow faucet (signed in): it sends QBFT test tokens, to each wallet once every 6 hours per chain
- Create a test payment (test prices go up to $5), go through the checkout, and watch the webhook fire
Use a tool like ngrok to expose your local webhook endpoint if you're developing locally:
Shell
ngrok http 3000# Use the ngrok URL as your test webhook endpoint's URL in the dashboardMake a test payment, check your server logs, and confirm your payment.completed handler ran. Done.
Bonus: add subscriptions (5 more minutes)
One-time payments are great, but if you're building a SaaS, you probably need recurring billing. Here's how subscriptions work with QBitFlow:
JavaScript
import { DurationUnit } from 'qbitflow'; app.post('/subscribe', async (req, res) => { // The subscription exists, with the session's id, once the customer signed. const session = await client. checkoutSessions. createSubscription( { productName: 'Pro plan', description: 'Monthly access', price: 4.99, // USD per period frequency: { value: 1, unit: DurationUnit.Months }, reference: 'order-1043', successUrl: `https://yoursite.com/success?uuid=${Placeholders. UUID}`, cancelUrl: 'https://yoursite.com/cancel', }); res.redirect(session.link);});The API looks almost identical to one-time payments: you add a frequency.
Here's what happens under the hood: at checkout, your customer signs one allowance through a smart contract, for a number of periods with a maximum per period. The first period is billed at signing. After that, QBitFlow bills one period on each due date, within what they signed. The funds stay in your customer's wallet until each bill: nothing is locked up or escrowed. Subscriptions are paid in tokens (like USDC), not in a chain's native coin.
No manual charging. No cron jobs to trigger payments. No chasing expired cards.
Managing subscriptions
You don't need to poll. QBitFlow sends a webhook for every step: subscription.created when it starts, subscription.billed for each bill, subscription.statusChanged on every status change, and subscription.actionRequiredChanged when your customer has something to do.
To decide access, use one rule: grant access while now is before currentPeriodEnd, whatever the status. hasAccess does exactly that:
JavaScript
import { hasAccess } from 'qbitflow'; const subscription = await client. subscriptions. get( subscriptionUuid);if (hasAccess(subscription)) { console.log('serve the premium content');} else { console.log('access ended: show the renewal page');}The status tells you why it stands where it is:
active: billed on its due dates. If itsactionRequiredistopUpAllowance, the allowance covers about one more period: your customer is prompted to top up from their own page.pastDue: a bill failed. QBitFlow retries it 1, 3, 5 and 7 days after the first failure, then cancels the subscription. Your customer can fix it from their page in the meantime (top up, or add funds).pausedorstopped: paused by your customer, or cancelled during its period. Paid through it all the same.- Check the full list of subscription statuses for the rest (
trial,trialExpired,cancelled).
You can also walk every bill of a subscription:
JavaScript
// Every bill, newest first: the iterator fetches the pages lazily.for await (const bill of client. subscriptions. iterateBills( subscriptionUuid)) { if (bill.periodEnd) console.log(`${bill.uuid}: ${bill.amount} USD, paid until ${bill.periodEnd}`);}Testing subscriptions
In test mode, a subscription is billed only when you ask, so you don't wait for the due date:
JavaScript
// Test mode only: runs the next billing now, with live's statuses and webhooks.const state = await client. subscriptions. executeTestBilling( subscriptionUuid);console.log(`billing ${state.stage}: ${state.outcome ?? 'running'} ${state.failureCode ?? ''}`);Note: This only works in test mode (and not before the next due date). In live mode, QBitFlow bills each subscription on its due date.
Why this approach works
If you've integrated Stripe before, this probably felt familiar. That's intentional. But there are some key differences worth understanding:
Non-custodial. Funds go directly from your customer's wallet to yours via smart contracts. QBitFlow never holds your money. There's no "balance" to withdraw: it's already in your wallet.
Open-source smart contracts. Every payment flows through contracts you can read on GitHub. No black boxes.
0.99%, down to 0.5% with volume. No per-transaction fixed fee. No withdrawal fees. No hidden charges. On a $10 payment, that's $0.10, compared to $0.59 with Stripe's 2.9% + $0.30. The network fee is separate, and your customer pays it on top.
Zero chargebacks. Blockchain transactions are final. No disputes, no fraud reversals, no chargeback fees. Refunds are yours to send, from your dashboard.
No account for your customers. If your customer has a crypto wallet, they can pay. They pick a chain and coin, connect, and sign.
QBitFlow vs. Stripe: quick comparison
| Stripe | QBitFlow | |
|---|---|---|
| Fee | 2.9% + $0.30 | 0.99%, down to 0.5% with volume (network fee apart) |
| Setup | Business verification required | Sign up by email, start in test mode |
| Chargebacks | Yes (+ $15 fee) | None (on-chain payments are final) |
| Payouts | 2-7 day rolling basis | None needed: paid to your wallet once the transaction confirms |
| Custody | Stripe holds funds | Non-custodial (your wallet) |
| DX | Excellent | Excellent |
This isn't a "Stripe bad" argument. Stripe is great for card payments. But if you want to accept crypto, or your users are asking for it, QBitFlow gives you the same developer experience on crypto rails, with lower fees and less friction.
What's next
You've got a working crypto payment integration. Here's where to go from here:
- API documentation: the full reference for every endpoint, webhook event, and SDK method
- GitHub: SDKs, smart contracts, and example projects
- Dashboard: manage payments, brand your checkout page, view transaction history
The whole point of this tutorial was to show you that adding crypto payments isn't some massive undertaking. It's an API integration. You've done dozens of those.



