QBitFlow
Get started

Guide

Bill subscriptions

Bill your customers' own wallets every period, from one signature. Every step playable in test mode.

What you'll build

  1. Your server → QBitFlow API: Creates a subscription checkout
  2. QBitFlow API → Your server: Its link and sub@… id
  3. Customer wallet → QBitFlow API: Signs the spending cap, once
  4. Customer wallet → Payment contract, on-chain: Bill 1, at signing (none in a trial)
  5. Payment contract → Your wallet, on-chain: Your share, QBitFlow's fee split off
  6. QBitFlow API → Your server: subscription.created: access to accessUntil
  7. QBitFlow API → Payment contract: Bills on each due date
  8. Customer wallet → Payment contract, on-chain: Each bill, never past the cap
  9. Payment contract → Your wallet, on-chain: Your share of each bill
  10. QBitFlow API → Your server: subscription.billed, statusChanged: access until accessUntil
Blue mark: money, on-chain. The rest moves no funds.
  • Plans, with an optional free trial, and a checkout your customer signs once
  • Access granted and revoked from webhooks, by one simple rule
  • Failed bills and cancellations handled, the whole timeline played in test, then live

For a SaaS or a membership. At checkout your customer signs a spending cap once: a number of periods, at most a set amount each. Each due date bills one period from their wallet, nothing prepaid, and they top up, pause or cancel from their own page (subscriptions). The business side is on recurring payments.

cancelled · nothing more can be pulled

The steps

  1. Step 1: Set up your account, test mode and an API keyAn account, the dashboard in test mode, a wallet that accepts a token and an API key, then a client that checks the key on start-up.
  2. Step 2: Plans, with an optional free trialA plan is a product with billing terms: how often it bills, an optional free trial, a minimum number of periods. Create it once, sell it many times.
  3. Step 3: Subscribe a customerCreate a subscription checkout, send your customer to it, and keep its sub@ id: it's the subscription's id from the first second to the last.
  4. Step 4: Grant and revoke accessReceive the subscription webhooks, and grant access while now is before accessUntil, whatever the status. One rule, no state machine to keep.
  5. Step 5: Failed bills, retries and the customer's own pageWhen a bill can't be charged, QBitFlow retries it over a week and tells you why each time. Tell your customer what to do; their own page does the rest.
  6. Step 6: Cancel and refundEnd a subscription at once or at the end of its paid period, know what your customer's own cancellation does, and refund a bill.
  7. Step 7: Test billing, then go liveRun any subscription's next bill on demand in test mode, walk the whole billing timeline once, then move it all to live.

Before you start

  • A server that keeps a secret (your API key) and receives HTTPS from the internet (your webhooks).
  • A wallet that accepts at least one token, on a network QBitFlow supports (Ethereum, Base and Solana): subscriptions are paid in tokens, not a chain's own coin.
  • One of the four SDKs (TypeScript, Python, Go and PHP), or plain HTTP: every example also comes in cURL.
  • Coming from the Sell guide? Your set-up carries over. If your endpoint listens for three types only, widen it to every type before your first subscriber.