Checkout sessions

Authentication & roles

• A member creates subscription checkouts while the organization's members.subscriptions policy allows it (on by default; off → 403 policy_disabled, one-time payments only); the team always can. The policy covers the other ways to sell a subscription too: giving a product subscription terms (Products) and the link of a member's subscription product (Payment links).
• A member opens checkouts (both create routes, from the dashboard or their own key, inline or of a product) while the organization's members.products policy allows it (on by default). Off → 403 policy_disabled, details.policy: "members.products" (checked before members.subscriptions): the member is paid only through the organization, which still opens checkouts in their space (switched into it, or On-Behalf-Of with an organization key). GET /checkout-sessions/:uuid and POST /checkout-sessions/:uuid/expire are refused the same way (403 policy_disabled: the organization reads and expires the checkouts opened for the member). The team passes, acting in the member's space too. The links of the products in their space are closed too (Payment links).
• A checkout session is named by its prefixed id (pay@…, sub@…: also the id of the payment or subscription it creates) or its bare uuid, on every :uuid route; a malformed value → 400 validation_failed on uuid.

Creating a session

• Idempotency-Key (idempotency): both creates take one. A create retried with the same key (a timeout, a 5xx) answers the first CreatedCheckoutSession again (the same uuid, link and expiresAt, Idempotent-Replayed: true) for 24 hours, and opens no second session (so no second checkout.expired later for an order paid on the first). SDKs send one on every create.
• Success is HTTP 201 with a CreatedCheckoutSession { link, uuid, expiresAt } (all three always present). The uuid is pay@-prefixed for a payment session and sub@-prefixed for a subscription session. expiresAt is when the checkout can no longer be paid. If it wasn't paid by then, checkout.expired is sent (Webhook events) and its status becomes expired. A payment sent right before the expiry is waited for (up to 3 hours) and completes normally.
• Lifetime. A session lives for QBitFlow's default lifetime (at most 24 hours; a session's expiresAt tells it), or expiresInMinutes (optional, an integer from 10 to 1440, and never longer than the default lifetime: 400 validation_failed on expiresInMinutes otherwise, its message giving the maximum). The merchant can end it earlier with POST /checkout-sessions/:uuid/expire.
• A checkout nobody could pay is refused: 409 merchant_not_ready, before anything is written (no reference held, no product or customer created), details.reason saying what is missing:
  • noWallet: the space's wallets accept no currency (no wallet yet);
  • organizationNoWallet: the organization holds the member's funds (the trust layer: its payments go to the organization's wallets) and the organization's wallets accept no currency;
  • noTokenWallet (subscriptions): subscriptions are paid in tokens and the space's wallets accept only native coins;
  • fundsHeld (subscriptions, trials included): the organization holds the member's funds (the member isn't trusted yet, Members and held funds). A held member sells one-time payments only: see § Subscription only below.

The hosted session's availableCurrencies lists what the checkout accepts (currency objects, Currencies): what the receiving wallets accept, tokens only for a subscription. Onboarding order for a space (the organization's, or a member's): its wallets and the currencies they accept first (dashboard), then products, then checkouts. A held member's payment checkouts are paid to the organization's wallets, so the organization sets up its own first.

• A space whose member was removed, or whose organization closed, opens no session: 410 merchant_closed. A session opened before is refused at its intent and at its send the same way (nothing is sent).
• An expired session is gone: its intent and its send → 404, as for an unknown session, even in the instant before the store forgets it. An intent never extends a session's life.
• A session a visit of a product's link opens (GET /pay/:productUuid, Payment links) is watched from its first intent, not from the visit: a visit nobody pays sends no checkout.expired.
• Product (payment & subscription): the request either names an existing product (productUuid or productReference) or gives an inline product (productName + priceUsd, description optional). Neither → 400 validation_failed on each of productName and priceUsd that is missing.
  • A payment checkout of a subscription product sells it once, at its price: its subscription terms are ignored, nothing recurs. Open a subscription checkout to bill it every period.
  • priceUsd is a JSON string holding an amount in USD ("12.50", "1000"): above 0, at most 1,000,000, at most 2 decimals (the usd validator). A JSON number, a negative amount, a third decimal or an exponent → 400 validation_failed on priceUsd. Responses write it back canonical ("12.5"). (It was price, a JSON number.) How large a price can be paid also depends on the token chosen at the intent (Payments and transactions).
  • Test mode: at most $5 (test tokens come from faucets with a limited supply). An inline priceUsd above it → 400 validation_failed on priceUsd, details.max: "5"; a product above it (one priced before the cap was enforced) → the same on productUuid or productReference, whichever named it. Checked before anything is written. Live mode has no cap.
  • productUuid is the product's uuid; a value that is not a UUID → 400 validation_failed on productUuid.
  • A named product must be one of the request's space's. Another space's (another member's, another organization's), an unknown uuid or an unknown productReference → 404 not_found.
  • An inline product of a payment is a snapshot: the session, and the payment it records, carry its productName, description and price, and no productUuid (no product is created). An inline product of a subscription names a hidden (isActive=false) product of the space, which the subscription's productUuid names: the one with the same productName, description and price, created by the first such checkout (checkouts with the same inline product share it). A checkout refused on its inputs, its customer, its reference or the space's readiness creates none. One refusal comes after it: a test-mode subscription whose amount with its fees is over the cap (400 validation_failed on fees, below) has already created the hidden product. It stays hidden and unlisted (GET /products shows it only with includeHidden=true), holds no checkout, and the next checkout with the same inline product reuses it.
  • The two forms are mutually exclusive: productUuid or productReference together with any of productName / description / priceUsd → 400 validation_failed on productUuid (or productReference, whichever was given).
  • Both session types accept both forms.
• Metadata (metadata, optional): your own data on the checkout (an order id, a CRM key), a map of strings. At most 50 keys; a key is 1–40 characters of A–Z a–z 0–9 _ - . :; a value at most 500 characters, without control or bidirectional characters. A broken limit → 400 validation_failed on metadata (too many keys, a malformed key: the key is never echoed) or metadata.<key> (its value). A key whose value is "" is dropped. The session's metadata is copied once onto what it creates: the payment (Payment.metadata, read-only, and payment.completed) or the subscription (Subscription.metadata, editable with PATCH /subscriptions/:uuid, and every subscription.* event). checkout.expired carries it. It is never shown to the customer (the hosted page, the public transaction reads). Never put secrets or personal data in it.
• Subscription only: never for a held member. In a member's space whose funds the organization still holds (the trust layer: the member isn't trusted yet, Members and held funds), a subscription checkout (with or without a trial) is refused: 409 merchant_not_ready, details.reason: "fundsHeld", before anything is written. A subscription's receiver is fixed on-chain when the subscriber signs, for the subscription's whole life: one created while held would pay the organization's wallet forever, and the organization would have to forward every bill by hand. Once the organization trusts the member (POST /members/:userUuid/trust), their subscription checkouts open and pay the member's own wallet. A subscription product's link (GET /pay/:productUuid) of a held member opens nothing (the not-found page, Payment links). A session opened before this rule is refused the same way at its intent (POST /hosted/subscriptions/intent), nothing signed or recorded. The organization's own space, and a trusted member, sell subscriptions as usual.
• Subscription only — durations. frequency and trialPeriod are Durations ({ "value": <uint32>, "unit": "seconds" | "minutes" | "hours" | "days" | "weeks" | "months" | "years" }, months = 30 days, years = 365 days). Every rule below answers 400 validation_failed with the field path in details.errors[].field:
  • unit must be one of the values above, and is required whenever value > 0 (frequency.unit, trialPeriod.unit).
  • A subscription product's terms are the defaults: with a productUuid (or productReference) of a subscription product, frequency, trialPeriod and minPeriods are all optional, and each one sent overrides the product's, the others kept. trialPeriod: { "value": 0 } and minPeriods: 0 remove the product's. The merged terms are validated as below (an override never gets around a rule).
  • frequency (the request's, else the product's) must be between a minimum and 1 year (frequency). The minimum depends on the mode: 1 hour live, 5 minutes in test mode (on a development server, live mode's minimum is 1 minute; test mode's stays 5 minutes). None at all (an inline product, or a one-time product, without frequency in the request), a zero value and a duration too long to count in seconds all fail on frequency. For a one-time product, the message names it: "Product <reference> has no subscription terms: pass frequency, or use a subscription product".
  • trialPeriod is optional. Omitted (without a product's), or { "value": 0 } (with or without a unit), means no trial. A trial longer than ~136 years → trialPeriod.
  • minPeriods is optional (0 to 1000).
  • A live subscription's price (inline, or its product's) must be above $0.25 → on priceUsd (or productUuid / productReference), details.min.
• The customer. customerUuid and customerReference are optional. Give either, and the checkout asks the customer nothing (asksCustomerDetails: false, whatever checkout.customerDetails says; details sent at the intent are ignored):
  • customerUuid must be one of the space's customers (in the session's mode); otherwise → 404.
  • customerReference is your reference of the customer: QBitFlow needs no customer for it. The space's customer with that reference, if there is one, is linked (the payment's customerUuid; also one created between the checkout and its payment); otherwise none is created. Either way the payment, or the subscription and each of its bills, keeps it as customerReference, which payment.completed, subscription.created and the accounting export carry. Without a customer QBitFlow has no name and no address: the buyer gets no receipt and no other customer email (billing failures included); your system tells your customer. To have QBitFlow email them, create the customer with that reference and their email first (POST /customers): one created any time before the payment is recorded is linked to it, and gets its receipt (the emails.customerReceipts setting still applies).
  • Neither: the checkout collects what checkout.customerDetails asks (below).
• successUrl and cancelUrl are optional (http_url, else 400); when absent, the merchant's checkout.defaults setting gives them. In live mode they must be https (the customer's browser goes there from the checkout): an http:// URL → 400 validation_failed on successUrl / cancelUrl, the setting's included (its message says so: change the setting, or give the URL). Test mode takes http (a local shop).
• A member gives a checkout's successUrl and cancelUrl while their organization's members.checkoutRedirects policy allows it (on by default: a member's shop or plugin sends the customer back to its own site). With the policy off for the member, a member (their session or their own API key) sending either → 403 policy_disabled with details.policy: "members.checkoutRedirects" and details.field (successUrl first when both are sent), nothing created: their checkouts go where the checkout.defaults setting says (the organization's). The team gives them for a member whatever the policy (switched into their space, or an organization key with On-Behalf-Of), and a qbf.cash handle gives its own (a person, with no organization above it).
• Redirect placeholders. In successUrl and cancelUrl (yours or the defaults'), QBitFlow replaces {{UUID}} with the session's prefixed id (pay@…, sub@…) and {{TRANSACTION_TYPE}} with its type (payment, createSubscription), e.g. https://shop.example/thanks?order=42&session={{UUID}}. The session keeps your URLs, placeholders filled: checkout.expired carries them as successUrl and cancelUrl. After a payment the customer first lands on QBitFlow's page for it (<checkout base>/manage?uuid=…), which then redirects to your successUrl; cancelUrl is used as is. A redirect proves nothing (anyone can open the URL): fulfil on the webhook (payment.completed, subscription.created) or GET /checkout-sessions/:uuid, never on the redirect alone.
• A session the merchant didn't name a customer for (no customerUuid or customerReference) records what the checkout asks: customerDetails is the merchant's checkout.customerDetails setting (email, or full, the default: first name, last name and email; absent when the setting is none), and asksCustomerDetails tells whether the intent must send them (true when customerDetails is present and no customer was named). The intent then requires those details (Payments and transactions). The customer is recorded with the payment or subscription (a free trial: when it starts), never at an intent: an intent nobody pays adds no customer. With none, nothing the checkout sends is kept.
• reference is optional. When set, it must not already be used by one of the space's payments (payment session) or subscriptions (subscription session), nor held by another open session of the space of the same kind → otherwise 409 (code: "unique_violation", details.field: "reference"). A payment and a subscription may share a reference: each kind has its own. A session holds its reference while it can be paid, and after that while a payment its customer sent still runs; one that expired unpaid (or that its merchant expired), or whose customer's last attempt failed and that is gone, hands it over. The recorded payments and subscriptions are checked at every creation, held or not. A payment or subscription confirmed on-chain is always recorded: should its reference be taken meanwhile (a session opened before references were held), it is recorded without one, and QBitFlow is alerted.
• Inline product fields: productName (the name rule, 2–100), description (optional, text, 2–500).
• reference, productReference and customerReference use the reference validator (1–100 characters: ASCII letters, digits and . _ : @ -). Anything else → 400 validation_failed on that field.

Fees — fees (payments and subscriptions)

A checkout may add amounts to its product's price: a tax, shipping, a service fee, and QBitFlow's processing fee when the merchant has the customer pay it. The customer sees them line by line and pays them with the price: once for a payment, with every bill for a subscription.

• The body: fees.items (optional, at most 10 lines: label, the name rule on one line, 1–40 characters; description, optional, the text rule, at most 200; amountUsd, the usd validator: a JSON string holding an amount above 0, at most 1,000,000, with at most 2 decimals) and fees.processingFee (optional boolean). Anything else on a line (a JSON number for amountUsd included) → 400 validation_failed on its path (fees.items[0].amountUsd, fees.items[0].label…); 11 lines → 400 on fees.items.
• The processing fee (processingFee: true, or omitted while the space's checkout.customerPaysProcessingFee setting is on; false turns it off for the checkout) is a last line {type: "processingFee", label: "Processing fee"} computed by QBitFlow on the price and the merchant's lines at the merchant's platform fee p (never below 0.5 %, the contracts' floor): base × p / (1 − p), rounded up to the cent. QBitFlow's fee is taken on everything charged, the processing fee included, so this gross-up is what leaves the merchant at least the price and their lines, as if no fee were taken ($100 + $20 VAT at 0.99 % → a $1.20 processing fee, $121.20 charged, $120.00 kept). The rate is the checkout's: the organization's fee when it is created (fees). The organization decides it for its members: a member's checkout (session or own key) may send fees.processingFee only when it equals the organization's checkout.customerPaysProcessingFee; a different value → 403 processing_fee_set_by_organization, details.field: "fees.processingFee". Omitting it follows the organization's value. The team, acting in a member's space too, is not checked. A marketplace's organization fee is not passed on: it is taken from that amount as on any payment.
• The session (the hosted page's, and checkout.expired's) carries fees (the lines, in the order to show them: the merchant's, then the processing fee; [] without any) and amountUsd: the price plus every line, what the customer pays before the network fee. priceUsd stays the product's. The lines are fixed when the session is created (a later setting or fee change doesn't alter them).
• What is charged is amountUsd: converted to the token at the intent (rounded down to its smallest unit), split by the contracts (QBitFlow's fee, the organization's, the referrer's are all taken on it), and recorded as the payment's amountUsd, with its priceUsd and fees (Payments and transactions). The network fee comes on top, quoted by the intent's breakdown.
• Test mode: amountUsd, fees included, is capped at $5 as a price is → 400 validation_failed on fees, details.max: "5".
• A subscription's lines are locked with its price. The subscription keeps them as fees (next to priceUsd, which stays the price), and every bill charges priceUsd plus the lines, as they were at signup: the first bill (paid at creation) and each next one, whatever the product's price or the merchant's platform fee becomes. The bill's amountUsd is that sum. The maximum per period and the allowance the subscriber signs are sized on it. A free trial names that amount in its message ("Then: … USD every …"), and its upgrade checkout keeps the trial's lines: the merchant's as they were, the processing fee computed again on the upgrade's price.
• A product link's checkout (GET /pay/:uuid, a payment's or a subscription's) applies checkout.customerPaysProcessingFee; a qbf.cash tip never has fees.

Session status — GET /checkout-sessions/:uuid

Tells the merchant that created a session where it stands, so an integration can tell a session still waiting for its customer from an abandoned one. (It was GET …/:uuid/status.)

• Response CheckoutSessionStatus: { uuid, status, txHash?, message?, lastAttempt?, expiresAt? }. uuid is the session's prefixed id, even when it was read by its bare uuid. status is one of four: created (open, waiting for the customer), waitingConfirmation (a transaction was sent), and the two final ones, completed and expired. txHash is set once the customer's transaction is sent (a completed subscription has none). message may explain an expiry. expiresAt is present while the session is open (when it can no longer be paid), and on the answer of POST /checkout-sessions/:uuid/expire (when it was expired); absent once the session is gone (completed, or expired at its time).
• A failed attempt is not a status. When the customer's transaction fails (funds, signature, network…), the session goes back to created with lastAttempt { status: "failed", code, message?, txHash?, at }: the error code (errors, e.g. insufficient_funds, token_not_approved, tx_not_sent), the reason, the attempt's transaction if it was sent, and when it failed. A transaction sent but not final in time is not a failed attempt (it may still land): the session stays waitingConfirmation while QBitFlow follows it, and can't be expired meanwhile (409) (Payments and transactions § Transaction status). While the session hasn't expired, the customer can try again from the same checkout; the next attempt replaces lastAttempt (waitingConfirmation, then completed, or another failed attempt). Never cancel an order on lastAttempt: fulfil on payment.completed / subscription.created (or completed here), give up on checkout.expired (or expired here). A session whose last attempt failed can be expired (below).
• A free trial's checkout sends no transaction: its subscription is created (and subscription.created sent, its status: "trial") when the customer starts it, while the session still answers created; once the session is gone it answers completed.
• Only the session's space sees it (spaces): the organization's sessions from its space, a member's from theirs, in the session's mode. Anything else → 404, never 403.
• A completed session keeps answering completed after it leaves the session store (a few minutes after completion): the recorded payment or subscription answers instead, with the same ownership rules.
• A session that expired unpaid, or that its merchant expired, answers expired (from its expiry: checkout.expired was sent) for as long as QBitFlow keeps its expiry's record (the workflow history's retention, days after the expiry), then 404. An unknown id, another owner's session, and a product link's visit never engaged are 404.
• :uuid: a prefixed session id (pay@…, sub@…) or its bare uuid (txuuid): malformed → 400 validation_failed on uuid. Another kind of id (refund@…) → 404.

Expiring a session — POST /checkout-sessions/:uuid/expire

Ends a session the caller created before its expiresAt (an order cancelled, a cart changed), so its customer can no longer pay it. No body.

• Success is 200 with the CheckoutSessionStatus { uuid, status: "expired", message, expiresAt } (expiresAt: when it was expired). From then on its intent and its send answer 404 (as an expired session), GET /hosted/checkout-sessions/:uuid answers 404, GET /checkout-sessions/:uuid answers expired, and checkout.expired is sent once, its data's expiresAt being when it was expired. Its reference is free again.
• Expiring an expired session (by its time or by its merchant) answers 200 again, with status: "expired": idempotent. Only the first answer carries expiresAt (when it was expired); a later one, the session being gone, doesn't.
• A session whose customer paid it, or sent a payment that still runs, or started its free trial, can't be expired: 409 tx_already_sent. A payment that failed doesn't prevent it. A payment sent in the instant before the expiry is waited for: if it completes, the answer is 409 and the payment is recorded (payment.completed).
• A product link's visit never engaged (no intent) can be expired too.
• Only the session's space may expire it: another space's or organization's session, or an unknown id → 404. :uuid malformed → 400 validation_failed on uuid. A GET → 405 method_not_allowed (Allow: POST).