Payments and transactions

The customer's receipt

• Once a payment is recorded, its customer is emailed its receipt, once: what was charged, the network fee on its own row, the total that left their wallet, the network, their wallet and the transaction on the explorer, all from the recorded split (settlement.split). Sent in the merchant's name; the setting emails.customerReceipts turns it off (on by default). Never in test mode, nor without a customer with an email. A receipt that can't be sent never affects the payment.

Authentication & roles

The v1 / beta paths are gone (/transaction/payments, /transaction/payments/combined, /transaction/payment/:uuid, /transaction/payment/reference/:reference, /transaction/failures, /transaction/info/:txUuid, /transaction/status[/ws], /transaction/payment[/intent], /transaction/payment/run-test-tx): 404.

• POST /hosted/payments/intent (and the subscription intent, Hosted subscriptions) takes customerInformation when the session has no customer: what its customerDetails asks is required: email → customerInformation.email; full → also the first name and lastName (400 validation_failed on customerInformation or the missing field); a session asking nothing (no customerDetails) → optional, and ignored (nothing is kept). The intent writes no customer: the details are kept with the session, and the customer is recorded with the payment (a subscription: with it; a free trial: when it starts), so an intent never paid adds none. The space's unverified customer with the same email, whatever its casing, is reused; a customer the merchant created (verified) never is, whatever its email: the payer's email then becomes an unverified customer of its own (a deleted customer is never reused either; Customers § Verified customers). customerInformation has no reference (the merchant's own id is never the customer's to give). Ignored when the merchant named the customer (customerUuid, or its own customerReference: the checkout then asks nothing, Checkout sessions § The customer).
• A payer who can't pay is told at the intent (payment, subscription): a wallet that doesn't hold the amount (with a 5 % margin for the price and the network fee) → 422 insufficient_funds (a token), 422 insufficient_native_funds (the chain's own coin), the codes the network's own refusal gives (errors). Nothing is prepared; top the wallet up and make the intent again. A signer that isn't an address of the currency's chain → 400 validation_failed on signer.
• The paying wallet can't be the receiving one: a signer that is the merchant's receiving wallet (or the organization's, while it holds the member's funds) → 400 sender_is_receiver, nothing prepared.
• A currency the checkout doesn't take: one of the catalog the session never offered, or one its merchant (or the organization) removed since it opened → 409 currency_not_accepted, details.currency (its code): pick another of the hosted session's availableCurrencies. A currency that isn't a code of the session's mode → 400 validation_failed on currency.
• Amounts fit the chain (an intent: payment, subscription, allowance): the price converted to the chosen token's smallest unit must fit what the chain holds, u64 on Solana, uint160 for an EVM token (Permit2), uint256 for an EVM chain's coin, and be at least one unit. Too large or below one unit → 400 validation_failed on currency (another token may hold it); a subscription's allowance (a period's amount × numPeriods, with its buffer and network fees) too large → 400 validation_failed on numPeriods. Never truncated.
• The intent's and the send's uuid is the checkout session's pay@ id, or its bare uuid.

Spaces

• Every payment belongs to one space (spaces): the organization's or a member's, in one mode. Every route works in the request's space: the team (and organization keys) sees the organization's payments, a member (and their keys) their own, and an organization key with On-Behalf-Of: <userUuid> (or the dashboard switched into the member's space) the member's.
• A payment of another space, of another organization or of the other mode is never listed, and answers 404 by uuid: existence is never revealed. Another organization's payment uuid answers like an unknown one.
• Organization-wide lists (?includeMembers=true on both lists): the organization's space (the team's sessions, the organization's keys without On-Behalf-Of) lists its members' payments and bills too, in its mode only, each naming its member (userUuid; the organization's own have none). Every member's space of the mode is read, removed members' included (their data stays the organization's, Members and held funds § Remove), and so is the personal space an admin kept from before their promotion. From a member's space (a member's session or key, On-Behalf-Of, the dashboard switched into a member) → 400 validation_failed on includeMembers. Without it a list is the request's space only. A webhook's userUuid is the member to name in On-Behalf-Of for follow-up reads of that member's resources.
• One member's rows (?userUuid=<member> on both lists and the failures log): from the organization's space, owners and admins (and the organization's keys, capped at admin) read that member's rows only, without switching into their space or On-Behalf-Of: the marketplace dashboard's drill-down. A member removed from the mode still reads; a user who isn't a member in this mode → 404; from a member's space → 400 validation_failed on userUuid; with includeMembers → 400 on userUuid.
• Organization-wide reads by uuid: GET /payments/:uuid?includeMembers=true (and GET /bills/:uuid, GET /subscriptions/:uuid, Subscriptions and bills) read a member's row from the organization's space, in its mode, with its userUuid: the row a list with includeMembers showed. Same rules as the lists (a member's space → 400 on includeMembers; another organization's or the other mode's → 404). Read only: refunding it still switches into the member's space (or uses On-Behalf-Of).

Reads

• GET /payments/:uuid returns one of the space's payments, by its pay@-prefixed uuid (the value emitted as the payment's uuid, its checkout session's) or its bare uuid. Unknown uuid, another kind of id (sub@…: it isn't a payment), another space's or mode's → 404; malformed → 400 validation_failed on uuid.
• By reference: GET /payments?reference=<reference> (it was GET /transaction/payment/reference/:reference): the list filtered on the merchant's reference, an envelope of 0 or 1 item (items: [] when no payment has it; never 404). References are unique per space, so with includeMembers (or userUuid) it may list one per space read. reference follows the reference validator (max=100): anything else → 400 validation_failed on reference.
• GET /payments and GET /transactions are cursor-paginated (pagination): the envelope { items, hasMore, nextCursor? }, nextCursor present only when hasMore; ?limit= (20 by default, at most 100: larger is clamped) and ?cursor= (the previous page's nextCursor, verbatim: anything else → 400 validation_failed on cursor).
• Order: newest first, by createdAt (when the payment or the bill was recorded) then uuid, both descending. Rows recorded at the same instant are told apart by their uuid, so a walk visits every row exactly once, whatever the page size.
• Filters (both lists, each optional, combined with AND): customerUuid, productUuid, createdAfter, createdBefore (RFC 3339 instants or dates, both excluded; pagination), includeMembers, userUuid (above), refunded (true: only the rows with an approved refund, what a "Refunded" badge means; false: the others, a pending or rejected refund included). GET /payments also takes reference (above). GET /transactions also takes type (payment or bill: one kind of row; it was source, with subscriptionHistory) and subscriptionUuid (sub@… or a bare uuid: that subscription's bills only, so no payment row; another space's subscription gives an empty list). A malformed value → 400 validation_failed on its name (type: one of the two values).
• The transactions feed (GET /transactions, it was GET /transaction/payments/combined) merges one-time payments and subscription bills into Transaction rows, each with its type (payment or bill; it was source). A row reads like its resource (Payment or Bill): amount / amountMinUnits / amountUsd, currency, priceUsd and fees (a bill's are its subscription's locked price and lines, what each bill charges; priceUsd absent on a bill of a subscription without a locked price), productName, productDescription, settlement, confirmedAt, paid / paidMinUnits / paidUsd, refund / refundable, customer, metadata (a payment's; {} on a bill: its subscription's is on the subscription), and for a bill its subscriptionUuid, subscriptionReference, periodStart and periodEnd.
• References: a payment row carries its own reference (when it has one). A bill has none of its own (billing runs automatically), so it carries subscriptionReference, its subscription's reference, as the subscription webhooks do. Each is absent when empty. reference, customerUuid, metadata and settlement are the merchant's (whenAuth), as on Payment.

Response fields

• A payment's uuid is written with its pay@ prefix (a bill's sub-hist@).
• Absent means no value (naming): reference, customerUuid, customerReference, productUuid, productDescription, note, refund, confirmedAt (only on records made before it was recorded: § When), paid*, userUuid (the organization's own) are absent when they have none (never null or ""). fees is always present ([] without any), metadata too ({}).
• userUuid, customerUuid, customerReference, reference, note, customer, metadata, settlement, paid* and the refund state are the merchant's (resource:"whenAuth"): present on the authenticated reads, never on the hosted pages' public reads. A payment names no organization.
• productUuid names the product paid for; absent when the payment has none (an inline product).
• The currency is the currency object (Currencies: id, code, symbol, name, chain, decimals, address, mainCurrencyId, test) on Payment and Transaction rows; the currencyId key is gone.
• Where to check it: chain (ETH, BASE or SOL: the chain it was paid on; a test-mode payment's is that chain's testnet, test: true) and explorerUrl (its transaction on the chain's block explorer: Etherscan, Basescan, Solscan, their testnets' in test mode) on Payment, bills, Transaction rows, refunds, and in payment.completed and subscription.billed. Link to explorerUrl rather than building explorer links: QBitFlow may change explorers.
• Merchant metadata (metadata): the checkout session's metadata, copied once when the payment is recorded (Checkout sessions § Metadata). Read-only on the payment (no route changes it); {} when the checkout had none (a product link's visit, a tip). payment.completed carries it. Never on the hosted pages.
• The settlement (settlement, the merchant's; it was metadata): how the payment settled: feePercent (QBitFlow's fee, a percent string), organizationFee / referralFee (feePercent, address; absent without one), split (below) and transaction (blockNumber, blockTime, gasUsed, fee and Base's l1Fee in the chain's native coin, nativePriceUsd; absent before the confirmation). referralFee never shows its referral's id nor its terms (until when the referrer earns its share).

Who paid (customer)

• Every payment, bill and transactions row (and subscription, refund) names its customer (merchant only, API reads): customer: { uuid, firstName, lastName?, email, reference?, deleted }, read with the row, one lookup per page. Absent when the row has no customer. Webhooks keep customerUuid only.
• A deleted customer still names its rows, with deleted: true (while GET /customers/:uuid answers 404).
• A customer is always read in its row's own space: a row never names another space's customer.
• A transactions row also carries customerReference, as Payment does.

Refund state (refund, refundable)

On Payment, bills and Transaction rows (merchant only, API reads):

• refund: the transaction's refund, if any (uuid, status, initiatedBy, refundPercent, amount, amountMinUnits, amountUsd, createdAt, respondedAt: the Refund fields of the same names, Refunds). One refund per transaction, whatever it became: a payment is never refunded twice (a partial refund isn't followed by another). Its uuid and status are what a "refunded" badge needs (no flat refundUuid / refundStatus keys: one name per concept).
• refundable: whether a refund would be accepted now (the customer's request, the merchant's POST /refunds/intent). false with notRefundableReason:
  • heldFundsReleased: held for a member and released to them since (checked first);
  • refundExists: it has its refund (a customer's request, pending or answered, or a merchant's refund sent and confirmed). A merchant's refund prepared or being confirmed isn't recorded yet: refundable stays true until it confirms (its intent then answers 409 refund_already_exists).
• paid / paidMinUnits / paidUsd: everything the customer paid, the refund's base (Refunds § What a refund pays back), from the recorded split. Absent when the split wasn't recorded.

When (confirmedAt, checkoutOpenedAt)

• confirmedAt (payments and bills alike): when the chain confirmed it, its block's time (settlement.transaction.blockTime, the same instant). When the chain's node doesn't give the block's time, both are the time QBitFlow recorded the confirmation (to the second), so every payment and bill recorded with its settlement.transaction has one; it is absent only on records made before QBitFlow recorded it (and then settlement.transaction.blockTime is absent too). createdAt is when QBitFlow recorded the payment, moments after its block.
• checkoutOpenedAt (payments): when its checkout session was created (the payment's uuid is the session's).

What the amounts mean

• USD amounts are decimal strings (naming): amountUsd, priceUsd, paidUsd, a fee line's amountUsd, every …Usd: the exact value, canonical ("12.5", "1000", "0"), never a JSON number. Computed values (a split part, a network fee) have at most 6 decimals.
• Token amounts come in pairs: amount (in the currency's units, exact: "12.5") and amountMinUnits (the on-chain integer: "12500000"), with amountUsd next to them. amount changed meaning: it was the USD amount (a number); it is now the token amount, and the USD value is amountUsd.
• amountUsd is what the customer paid, in USD (the price, at the checkout, plus a payment's fees), on Payment, bills and Transaction rows alike; amount / amountMinUnits the same in the currency. It is what the contracts split.
• A payment's priceUsd is its product's price at the checkout (it was price, a number), and fees what its checkout added (Checkout sessions § Fees: the merchant's lines and the processing fee the customer paid, {type, label, description?, amountUsd}, [] without any): amountUsd = priceUsd + Σ fees.amountUsd. On payments recorded before fees existed, priceUsd is amountUsd and fees is []. QBitFlow's fee is taken on the amount; with a processing fee, the merchant's share (settlement.split.merchant, plus organization on a member's payment) is at least the price and the other lines.
• settlement.split is how the contracts split it, each part a token amount { amount, amountMinUnits, amountUsd }: platform (QBitFlow's fee), referral (the referrer's share of QBitFlow's fee, apart from platform), organization (the organization's fee on a member's payment) and merchant (what the merchant's wallet received, or what the organization owes a member whose funds it holds); organization and referral are absent when none. platform + referral + organization + merchant = amount, exactly, in each unit (the USD parts are rounded to 6 decimals, the merchant's computed last so they add up to amountUsd). QBitFlow's fee as the accounting export counts it (platformFee) is platform + referral.
• settlement.split.networkFee is the network fee the customer paid on top of the amount, in the token (absent on payments recorded before it was; "0" when none): not part of the amount, nor of the split. Everything the customer's wallet sent is paid (amount + networkFee): a refund's base (Refunds). settlement.transaction.fee is something else: what the transaction cost its sender, in the chain's native coin.
• Show the split as recorded: never recompute it from the rates (settlement.feePercent, settlement.organizationFee.feePercent), which round per step.
• productName and productDescription (they were name and description) are a copy of what was paid for: a payment keeps its checkout's product (the product's name and description when the checkout was created, or its inline ones), a bill its subscription's product when it was billed (the first bill: the checkout's). Editing or deleting the product later never changes them.

Failed payment attempts (GET /payment-failures)

The failures log (it was GET /transaction/failures): every attempt a customer made to pay and couldn't, for the dashboard (why customers fail, and what it costs). A failure is never money: never a payment or a bill, never in the payment lists, the accounting export, the ledger or the metrics' volume (metrics.md counts them apart, under failures). No webhook announces one.

• What is logged: an attempt the payer signed and sent, or that was refused at send:
  • kind: payment: a one-time payment's attempt; txUuid is pay@…, the uuid its payment has once paid;
  • kind: subscriptionCheckout: a subscription checkout's (its first bill, or a trial's start); txUuid is sub@…, the subscription's uuid once created;
  • kind: bill: every failed bill (sub-hist@…, the bill's uuid once paid), with its subscriptionUuid, the notice of a bill waiting for a new maximum included (category: maxAmountExceeded).

Never an intent refused (a wallet that can't pay is refused at the intent, before anything is signed), never a checkout left to expire, never a bill of a paused or stopped subscription (not billed: nothing failed).

• A failure's own uuid is a plain uuid (no prefix): a failed attempt isn't a transaction.
• Once per attempt: an attempt recorded again (a retried step) is still one row. attempt numbers a transaction's failed attempts from 1; a bill's is its dunning's attempt, and the notice of a new maximum spends none (it carries the last attempt's number).
• code is the error code the payer got (errors), message what they were told (absent when nothing was), createdAt when it failed. category is what the code means, one table for every kind:

| category | Codes | |------------|-------| | insufficientBalance | insufficient_funds, insufficient_native_funds | | allowanceExhausted | insufficient_allowance, allowance_expired, allowance_too_low | | approvalRevoked | token_not_approved | | maxAmountExceeded | max_amount_exceeded | | reverted | tx_failed | | notConfirmed | tx_not_sent (and tx_not_confirmed, no longer sent: only on failures recorded before, errors) | | signatureRejected | invalid_signature, signature_expired | | other | any other code |

A new code may join a category (or other); a new category is a new enum value (clients with exhaustive switches must handle it).

• What the customer tried to pay, never received: attempted (in the currency's units), attemptedMinUnits (its smallest unit) and attemptedUsd (a decimal string; it was a number), in currency (the currency object; it was currencyId). from: the customer's wallet. txHash: the transaction, when one of this payment was sent (a revert, a timeout); absent otherwise (refused at send, or the hash a payer sent was another transaction's). productUuid when it had a product. customerUuid and customer (as on payments, § Who paid) when QBitFlow knows the customer: a bill's always, a checkout's when the merchant named the customer (a new payer's details are only recorded with their payment).
• Order and pages: newest first, by createdAt then uuid; the list envelope (pagination), limit 20 by default, at most 100.
• Filters (each optional, combined with AND): kind, category (a value not listed → 400 validation_failed on its name), subscriptionUuid (sub@… or a bare uuid: that subscription's bills), and the list filters customerUuid, productUuid, createdAfter, createdBefore, includeMembers, userUuid (as the payment lists: § Reads, § Spaces; each member's row names its userUuid).
• Spaces: the request's space, each mode its own; another organization's attempts are never listed.
• Kept 25 months (the dashboard's window, and the month before), then deleted.