Merchant Guide
Recurring USDC Billing for Crypto SaaS and APIs: Stop Renewing Customers by Hand
QBitFlow Team
9 min read
On this page · 10 sections
Somewhere on your pricing page, or in a support macro, there is a line like "Crypto: annual plans only."
You know why it's there. Your customers already hold USDC and pay from their own wallets, and a monthly plan paid that way is a monthly chore for you. Someone emails a payment link each cycle. The customer pays it, eventually. Someone checks the explorer, matches the transfer to an account and switches access back on. Then the ticket arrives: "sent it, can you turn my access back on?"
The expensive case is the customer who never writes in. Their plan ran out, the link sat unread, and nobody on either side decided anything. They lapsed without choosing to leave.
So your crypto payers get a worse deal than your card payers: prepaid, annual, manual. This guide covers how to close that gap with recurring USDC billing your customer approves once, and where it doesn't fit.
Why crypto subscriptions end up manual
A card is a pull payment. The customer hands over a credential once and you charge it every month.
A wallet is push. Nothing leaves it without the holder's signature, so nobody can charge it on the 1st of the month: not you, not a processor. Every workaround follows from that. You sell a year upfront. You hold a prepaid balance, which makes you the keeper of money you haven't earned yet. Or you send a link each cycle and wait.
Each of those hands the work to your customer or to your team. What's missing is a way for the wallet holder to say, once: "bill me this much, on this schedule, and no more."
How recurring USDC subscriptions work when the customer signs once
That statement exists on-chain as an allowance, and QBitFlow subscriptions are built on it. One limit first: subscriptions bill tokens only (USDC, USDT or EURC, on Ethereum, Base or Solana). Native ETH and SOL aren't billed.
- Your customer signs once. At checkout they pick a token and a number of periods, then sign an allowance: that many bills, each capped at a maximum per bill.
- Nothing is prepaid. The first period is charged at checkout. The money for later periods stays in their wallet until each bill is due.
- Each bill is pulled on its due date. QBitFlow's relayer (the docs call it the operator) sends the bill to the contract, within about 10 minutes of the due date. The contract refuses a bill sent early and a bill above the maximum your customer signed.
- You're paid in the same transaction. The contract splits each bill as it charges it: your share goes to your wallet, the fee goes to QBitFlow. There is no QBitFlow balance in between and no payout to wait for.
- The price is locked at signup. Each bill charges the USD price your customer subscribed at, converted to their token on the day. A new product price applies to new subscribers only.
If the token's price moves far enough that a bill would exceed the signed maximum, the bill isn't forced through. It waits up to 7 days for your customer to sign a new maximum. With a dollar stablecoin that rarely comes up; EURC follows the euro, so its amount per bill moves with EUR/USD.
When a stablecoin subscription bill fails
Here is what happens when a wallet is short on the due date or an allowance runs out:
- Before the due date. You receive
subscription.upcomingBill(3 days ahead by default), which says whether the wallet's balance and allowance cover the coming bill. - The bill fails. The subscription becomes
pastDueand you receivesubscription.billingFailedwith the reason (insufficientBalance,allowanceExhausted,approvalRevoked) and the date of the next attempt. - Retries. The bill is retried 1, 3, 5 and 7 days after the first failed attempt, and at once when your customer tops up their allowance or raises their maximum.
- The last attempt fails. The subscription is cancelled, with
cancellationReason: "billingFailed".
A failure on QBitFlow's side (a network or a price unavailable) is retried every 30 minutes, spends no attempt and never cancels a subscriber.
Your customer fixes things on the subscription's management page, and you get its link (managementPageLink) on every read and every subscription webhook. It needs no account: the link identifies the subscription, and each action is signed by the wallet that subscribed. From it they see their recent bills, top up the allowance, raise the maximum, pause and resume, cancel, and confirm a trial. Pausing and resuming are signed messages (no transaction, no gas), and only the customer can pause. A cancellation stops billing and keeps the period they paid for.
Billing emails are settings you control, sent in your name, in live mode only: a warning before a bill that wouldn't go through (on by default), a reminder before every bill (off by default), a notice on each failed attempt, and a receipt for each paid bill.
Integration: one call, one id, signed webhooks
You create a checkout session and send your customer to its link:
http
POST https://api.qbitflow.app/v2/checkout-sessions/subscriptionX-API-Key: sk_live_… { "productName": "Pro API plan", "priceUsd": "29.99", "frequency": { "value": 1, "unit": "months" }, "reference": "sub_8841", "customerReference": "user_1207"}The answer is 201 with link, uuid (a sub@… id) and expiresAt.
That uuid is the subscription's id for life. Store it next to your account record: every later webhook and read names it. reference and customerReference are your own ids and come back on the subscription, so GET /subscriptions?reference=… finds it too. One detail to get right: if your customerReference matches no QBitFlow customer, nobody receives receipts or billing emails. Create the customer with their email first if you want them sent.
Then drive access from webhooks, never from the checkout redirect:
subscription.created: grant access. Its firstsubscription.billedfollows.subscription.billed: a renewal was paid, through the bill'speriodEnd.subscription.billingFailed: tell your customer what to fix. The event carries the management link.subscription.statusChanged: every status change (pastDue,paused,stopped,cancelled, back toactive).
One rule keeps this simple: grant access while now is before accessUntil, whatever the status. A check on status == "active" would cut off a customer who cancelled but has paid through the end of the month. The SDKs ship a hasAccess(subscription) helper that applies the rule.
Webhooks are signed (QBitFlow-Signature, an HMAC-SHA256 you verify locally) and delivered at least once, so deduplicate on the event id. If your card billing runs on Stripe, the subscriptions guide maps each Stripe event to its counterpart.
Free trials without a payment
A trial starts with one signed message. No payment, no gas, no funds move, and the message authorizes nothing. There is one trial per wallet and product.
A trial does not turn into a paid subscription on its own, because nothing was signed that could be billed. To continue, your customer confirms from their wallet: they sign the subscription itself, an on-chain transaction. Ahead of the trial's end (3 days by default) you receive subscription.upcomingBill with trialEnding: true. A trial that ends unconfirmed becomes trialExpired, your customer is emailed the link to confirm (a setting), and they have 7 days before it is cancelled. Once confirmed, it is the same subscription under the same id, now active, with its first bill.
Plan your funnel around that: your customer says yes twice, once to try and once to pay.
Who this is not for
- Your customers pay from exchange accounts. An exchange withdrawal can't sign an allowance. Subscribers need a wallet they control.
- You need native ETH or SOL billing. Subscriptions are token-only: USDC, USDT, EURC.
- Your customers are on Tron or BNB Chain. The supported networks today are Ethereum, Base and Solana. There are no dates to share for others.
- You need fiat in your bank account. You receive the token your customer paid, with nothing exchanged along the way. Turning it into fiat happens outside QBitFlow, through an exchange or off-ramp provider you choose.
- You bill metered usage. Each bill charges the fixed price your customer signed up at. To move a subscriber to a new price, you cancel at period end and send a new checkout.
On security and trust
The contracts are open-source at github.com/QBitFlow, and the Ethereum and Base contracts are verified on Etherscan and Basescan. They are not formally third-party audited yet; that is on the roadmap.
What the design limits: there is no QBitFlow balance holding your revenue or your customers' prepayments, so there is no pool to drain or delay. The allowance your customer signs is bounded in count and in size per bill, and the contract enforces both.
What it doesn't remove: smart-contract risk, the security of your own wallet, and token risk on the stablecoin itself. Bills also depend on QBitFlow's relayer to be sent. If it is down, bills wait and are retried, and no subscriber is cancelled for it.
Pricing
You pay 0.5% on your first $5,000, then 0.99%, 0.75% or 0.5% depending on your trailing 30-day volume (under $50,000, $50,000 to $100,000, $100,000 and more). There is no monthly fee and no setup fee. EXAMPLE: a 100 USDC bill at the 0.99% tier puts 99.01 USDC in your wallet and 0.99 USDC with QBitFlow, in one transaction. During your first $5,000 the same bill nets you 99.50 USDC. The network fee is paid by your customer on top of the price, not out of your share.
FAQ
Can QBitFlow, or you, overcharge a customer?
No bill can exceed the maximum per bill they signed, and no bill can be sent before its due date: the contract refuses both. The total is bounded by the number of periods they authorized. When the allowance runs low, the subscription shows actionRequired: "topUpAllowance" and your customer decides whether to add periods. It is never extended for them.
What if a customer revokes the approval?
The next bill fails with the reason approvalRevoked and follows the retry schedule above. A subscription cancelled on-chain outside QBitFlow is cancelled on your side too, with cancellationReason: "inactiveOnChain". Either way nothing more is pulled, and a webhook tells you.
Who pays the network fee for each bill? Your customer, on top of the price. The relayer sends each bill and pays the network; the contract refunds that fee to QBitFlow in the token, out of the allowance, which is sized at checkout to cover it. On Ethereum and Base, a wallet using a token for the first time sends one approval to Permit2 and pays that gas in ETH. Solana needs no approval.
What happens to access while a subscription is pastDue?
That is your policy. accessUntil is already in the past, so the default rule ends access when the bill fails. To keep customers on during the retries (up to 7 days), add that grace period to your own check.
Can you migrate existing subscribers? Not automatically. A subscription exists only once a customer completes a checkout from their own wallet, so each existing subscriber signs once. One way to do it: at their next renewal, send the subscription checkout link in place of the usual payment link.
Is there a test mode?
Yes. A test key runs on test networks and never mixes with live. Periods can be as short as 5 minutes, and a test subscription is billed only when you call POST /subscriptions/:uuid/test-bill, with the same statuses and webhooks as live. You can walk the whole timeline, pastDue included, before going live.
See it, or test it
- See the customer and merchant flow: qbitflow.app/recurring-payments
- Run it in test mode: qbitflow.app/get-started, with the docs at qbitflow.app/docs



