Webhook events

allow read and create, (generated on creation of the payment link)

A prefixed id (pay@…, sub@…)

The amount in the currency's units, exact, a decimal string ("10" for 10 USDC): amountMinUnits / 10^decimals

The amount in the currency's smallest unit, a string of digits ("10000000" for 10 USDC, 6 decimals)

What the customer paid, in USD, a decimal string: the price (and, on a one-time payment, the fees its checkout added: fees), which the contracts split between QBitFlow's fee (the referrer's share included), the organization's fee and the merchant (settlement.split). The network fee a customer pays on top (settlement.split.networkFee) is not in it

The currency paid in, written as the currency object under currency (GET /currencies/:id)

Hash of the transaction in the blockchain

The chain it was paid on: ETH (Ethereum), BASE (Base) or SOL (Solana), the testnet's for a test-mode transfer (currency.test)

Its transaction on the chain's block explorer (the testnet's in test mode). Omitted without a txHash

Whether this is test data (testnets) or live data

Member the resource belongs to; omitted for the organization's own resources

Only for the resource's owner

The merchant's reference for the payment (an order or invoice id), set when creating its checkout. Only for the merchant: never in the public reads by uuid (GET /hosted/transactions/:txUuid)

Only for the resource's owner

PriceUSD is the product's price in USD, as the checkout had it, a decimal string, always present: amountUsd is the price plus the fees' lines. (A payment recorded before checkouts had fees has none stored: its price is its amount, Complete.)

What the checkout added to the price, line by line, as the customer saw them (a tax, shipping, the processing fee when the customer paid it); [] without any

What was paid for: the checkout's product name, as it was when the checkout was created (the product's, or the inline one). Later product edits don't change it

Same, for the product's description; absent without one

Metadata is the merchant's own data, copied from the checkout session that created the payment (its metadata), read-only. {} without any. Only for the merchant

Only for the resource's owner

The product paid for; omitted when the payment has none (an inline product)

The customer, when QBitFlow has one (named by the checkout, found by its customerReference, or recorded from the details the customer gave); omitted otherwise

Only for the resource's owner

The merchant's reference of the customer, as the checkout was given it (customerReference), whether or not QBitFlow has a customer with it; omitted otherwise

Only for the resource's owner

A qbf.cash tipper's message to the handle's owner (only for them); omitted without one

Only for the resource's owner

The customer, named (merchant only, API reads): who paid, even once deleted. Omitted without one

Only for the resource's owner

How it settled: its fees, its split and its transaction (only for the merchant)

Only for the resource's owner

When the chain confirmed it: its block's time (settlement.transaction.blockTime). Absent only on records made before it was recorded

Everything the customer's wallet sent, in the currency's units (a decimal string): the amount plus the network fee paid on top (settlement.split). A refund's base (refundPercent of it). Only for the merchant; absent when the split wasn't recorded

Only for the resource's owner

The same in the currency's smallest unit, a string of digits. Only for the merchant, like paid

Only for the resource's owner

The same in USD, at the payment's time, a decimal string. Only for the merchant, like paid

Only for the resource's owner

Its refund (one per transaction); omitted without one. The merchant's own refund appears once its transfer confirmed (approved)

Only for the resource's owner

Whether it can be refunded now

Only for the resource's owner

Why not: refundExists or heldFundsReleased. Omitted when refundable

Only for the resource's owner

When its checkout session was created (the payment's uuid is the session's). Omitted for a payment whose uuid doesn't say (made before UUIDv7s)

The payment's page for its customer

Its id (sub@…): the checkout session's

A prefixed id (pay@…, sub@…)

The merchant's reference for the subscription (an order or customer id), set when creating its checkout. Only for the merchant: never in the public reads by uuid (GET /hosted/transactions/:txUuid)

Only for the resource's owner

Its last change (a bill, a status, its metadata)

The subscriber's wallet: the one it bills. Absent when unknown (a trial not confirmed yet may have none)

The wallet its bills pay: the merchant's (or, while the organization holds a member's funds, the organization's)

Its product (GET /products/:uuid). Absent without one

The hash of the transaction that created the subscription on-chain. Absent until then (a trial, until its customer confirms it)

The currency (token) billed, written as the currency object under currency (GET /currencies/:id)

Billing interval in seconds, as on-chain (e.g. 2592000 = 30 days). Written as a types.Duration in responses and webhooks (e.g. {"value": 1, "unit": "months"})

SubscriptionStatus (status) is where it stands: trial, trialExpired, active, pastDue, paused, stopped or cancelled. Every change sends subscription.statusChanged. Don't grant access from it: grant access while now < accessUntil (docs/api/guides/subscriptions.md § Access)

ActionRequired is what its customer must do, if anything (absent: nothing): topUpAllowance (the allowance covers about one more bill at most), raiseMaximum (a bill waits for a new maximum per period), confirmTrial (the trial ended unconfirmed). Every change (set, changed or cleared) sends subscription.actionRequiredChanged

CurrentPeriodEnd is the paid-through date. A trial: its end. active, paused, stopped: the end of the period paid for (the next bill's due date). pastDue: the start of the unpaid period (past). cancelled: when it was cancelled, or the end of its last paid period if that came first. For access, read accessUntil: an active subscription is renewed a few minutes after this date

AccessUntil is when access ends: grant it while now < accessUntil, whatever the status. An active subscription: currentPeriodEnd plus 1 hour, since its renewal is billed within minutes of its due date (a subscriber whose bill is on its way keeps access; a failed bill sets pastDue). Every other status: currentPeriodEnd

PriceUSD is the price per period the customer subscribed at, in USD (a decimal string, e.g. "9.99"), locked at signup (a free trial's too): every bill charges it and its lines (fees), converted to the token at the bill's price. A later change of the product's price applies to new subscribers only. Never "0"

Fees is what its checkout added to the price, line by line, as the customer saw them (a tax, shipping, the processing fee when the customer pays it), locked at signup with the price: every bill charges priceUsd plus these lines. [] without any

AllowanceStatus (allowance) is what the subscriber's wallet still lets QBitFlow bill, and the most one bill may charge, at today's price. Absent during a free trial (nothing signed yet)

When it was last billed. Absent before its first bill (a trial)

When its next bill is due (a trial: when it ends; stopped: when it is cancelled). Absent once cancelled

When it was cancelled (absent until then, and for subscriptions cancelled before it was recorded)

Why it stopped or was cancelled: customer, merchant, billingFailed, trialNotConverted, merchantClosed or inactiveOnChain. Absent while it runs (and for subscriptions cancelled before it was recorded)

MinimumCancellationDate (cancellableAt) is the earliest its customer may cancel it (the checkout's minPeriods). Absent when they may cancel it any time

Metadata is the merchant's own key-value data: its checkout session's, copied when the subscription was created, then changed with PATCH /subscriptions/:uuid (merged). {} when none. Only for the merchant (API and webhooks)

Only for the resource's owner

ManagementPageLink is the subscription's page for its customer: where they top up its allowance, raise its maximum, pause, resume or cancel it, and confirm a trial. Share it with them (an email, the merchant's account page)

Whether this is test data (testnets) or live data

Member the resource belongs to; omitted for the organization's own resources

Only for the resource's owner

The customer, when QBitFlow has one (named by the checkout, found by its customerReference, or recorded from the details the customer gave); omitted otherwise

Only for the resource's owner

The merchant's reference of the customer, as the checkout was given it (customerReference), whether or not QBitFlow has a customer with it; omitted otherwise

Only for the resource's owner

The customer, named (merchant only, API reads): who paid, even once deleted. Omitted without one

Only for the resource's owner

The bill paid

Its subscription once the bill is paid: active (stopped, paused or cancelled if that happened while the charge was on its way), its next bill and its allowance

Its id (sub@…): the checkout session's

A prefixed id (pay@…, sub@…)

The merchant's reference for the subscription (an order or customer id), set when creating its checkout. Only for the merchant: never in the public reads by uuid (GET /hosted/transactions/:txUuid)

Only for the resource's owner

Its last change (a bill, a status, its metadata)

The subscriber's wallet: the one it bills. Absent when unknown (a trial not confirmed yet may have none)

The wallet its bills pay: the merchant's (or, while the organization holds a member's funds, the organization's)

Its product (GET /products/:uuid). Absent without one

The hash of the transaction that created the subscription on-chain. Absent until then (a trial, until its customer confirms it)

The currency (token) billed, written as the currency object under currency (GET /currencies/:id)

Billing interval in seconds, as on-chain (e.g. 2592000 = 30 days). Written as a types.Duration in responses and webhooks (e.g. {"value": 1, "unit": "months"})

SubscriptionStatus (status) is where it stands: trial, trialExpired, active, pastDue, paused, stopped or cancelled. Every change sends subscription.statusChanged. Don't grant access from it: grant access while now < accessUntil (docs/api/guides/subscriptions.md § Access)

ActionRequired is what its customer must do, if anything (absent: nothing): topUpAllowance (the allowance covers about one more bill at most), raiseMaximum (a bill waits for a new maximum per period), confirmTrial (the trial ended unconfirmed). Every change (set, changed or cleared) sends subscription.actionRequiredChanged

CurrentPeriodEnd is the paid-through date. A trial: its end. active, paused, stopped: the end of the period paid for (the next bill's due date). pastDue: the start of the unpaid period (past). cancelled: when it was cancelled, or the end of its last paid period if that came first. For access, read accessUntil: an active subscription is renewed a few minutes after this date

AccessUntil is when access ends: grant it while now < accessUntil, whatever the status. An active subscription: currentPeriodEnd plus 1 hour, since its renewal is billed within minutes of its due date (a subscriber whose bill is on its way keeps access; a failed bill sets pastDue). Every other status: currentPeriodEnd

PriceUSD is the price per period the customer subscribed at, in USD (a decimal string, e.g. "9.99"), locked at signup (a free trial's too): every bill charges it and its lines (fees), converted to the token at the bill's price. A later change of the product's price applies to new subscribers only. Never "0"

Fees is what its checkout added to the price, line by line, as the customer saw them (a tax, shipping, the processing fee when the customer pays it), locked at signup with the price: every bill charges priceUsd plus these lines. [] without any

AllowanceStatus (allowance) is what the subscriber's wallet still lets QBitFlow bill, and the most one bill may charge, at today's price. Absent during a free trial (nothing signed yet)

When it was last billed. Absent before its first bill (a trial)

When its next bill is due (a trial: when it ends; stopped: when it is cancelled). Absent once cancelled

When it was cancelled (absent until then, and for subscriptions cancelled before it was recorded)

Why it stopped or was cancelled: customer, merchant, billingFailed, trialNotConverted, merchantClosed or inactiveOnChain. Absent while it runs (and for subscriptions cancelled before it was recorded)

MinimumCancellationDate (cancellableAt) is the earliest its customer may cancel it (the checkout's minPeriods). Absent when they may cancel it any time

Metadata is the merchant's own key-value data: its checkout session's, copied when the subscription was created, then changed with PATCH /subscriptions/:uuid (merged). {} when none. Only for the merchant (API and webhooks)

Only for the resource's owner

ManagementPageLink is the subscription's page for its customer: where they top up its allowance, raise its maximum, pause, resume or cancel it, and confirm a trial. Share it with them (an email, the merchant's account page)

Whether this is test data (testnets) or live data

Member the resource belongs to; omitted for the organization's own resources

Only for the resource's owner

The customer, when QBitFlow has one (named by the checkout, found by its customerReference, or recorded from the details the customer gave); omitted otherwise

Only for the resource's owner

The merchant's reference of the customer, as the checkout was given it (customerReference), whether or not QBitFlow has a customer with it; omitted otherwise

Only for the resource's owner

The customer, named (merchant only, API reads): who paid, even once deleted. Omitted without one

Only for the resource's owner

Its id (sub@…): the checkout session's

A prefixed id (pay@…, sub@…)

The merchant's reference for the subscription (an order or customer id), set when creating its checkout. Only for the merchant: never in the public reads by uuid (GET /hosted/transactions/:txUuid)

Only for the resource's owner

Its last change (a bill, a status, its metadata)

The subscriber's wallet: the one it bills. Absent when unknown (a trial not confirmed yet may have none)

The wallet its bills pay: the merchant's (or, while the organization holds a member's funds, the organization's)

Its product (GET /products/:uuid). Absent without one

The hash of the transaction that created the subscription on-chain. Absent until then (a trial, until its customer confirms it)

The currency (token) billed, written as the currency object under currency (GET /currencies/:id)

Billing interval in seconds, as on-chain (e.g. 2592000 = 30 days). Written as a types.Duration in responses and webhooks (e.g. {"value": 1, "unit": "months"})

SubscriptionStatus (status) is where it stands: trial, trialExpired, active, pastDue, paused, stopped or cancelled. Every change sends subscription.statusChanged. Don't grant access from it: grant access while now < accessUntil (docs/api/guides/subscriptions.md § Access)

ActionRequired is what its customer must do, if anything (absent: nothing): topUpAllowance (the allowance covers about one more bill at most), raiseMaximum (a bill waits for a new maximum per period), confirmTrial (the trial ended unconfirmed). Every change (set, changed or cleared) sends subscription.actionRequiredChanged

CurrentPeriodEnd is the paid-through date. A trial: its end. active, paused, stopped: the end of the period paid for (the next bill's due date). pastDue: the start of the unpaid period (past). cancelled: when it was cancelled, or the end of its last paid period if that came first. For access, read accessUntil: an active subscription is renewed a few minutes after this date

AccessUntil is when access ends: grant it while now < accessUntil, whatever the status. An active subscription: currentPeriodEnd plus 1 hour, since its renewal is billed within minutes of its due date (a subscriber whose bill is on its way keeps access; a failed bill sets pastDue). Every other status: currentPeriodEnd

PriceUSD is the price per period the customer subscribed at, in USD (a decimal string, e.g. "9.99"), locked at signup (a free trial's too): every bill charges it and its lines (fees), converted to the token at the bill's price. A later change of the product's price applies to new subscribers only. Never "0"

Fees is what its checkout added to the price, line by line, as the customer saw them (a tax, shipping, the processing fee when the customer pays it), locked at signup with the price: every bill charges priceUsd plus these lines. [] without any

AllowanceStatus (allowance) is what the subscriber's wallet still lets QBitFlow bill, and the most one bill may charge, at today's price. Absent during a free trial (nothing signed yet)

When it was last billed. Absent before its first bill (a trial)

When its next bill is due (a trial: when it ends; stopped: when it is cancelled). Absent once cancelled

When it was cancelled (absent until then, and for subscriptions cancelled before it was recorded)

Why it stopped or was cancelled: customer, merchant, billingFailed, trialNotConverted, merchantClosed or inactiveOnChain. Absent while it runs (and for subscriptions cancelled before it was recorded)

MinimumCancellationDate (cancellableAt) is the earliest its customer may cancel it (the checkout's minPeriods). Absent when they may cancel it any time

Metadata is the merchant's own key-value data: its checkout session's, copied when the subscription was created, then changed with PATCH /subscriptions/:uuid (merged). {} when none. Only for the merchant (API and webhooks)

Only for the resource's owner

ManagementPageLink is the subscription's page for its customer: where they top up its allowance, raise its maximum, pause, resume or cancel it, and confirm a trial. Share it with them (an email, the merchant's account page)

Whether this is test data (testnets) or live data

Member the resource belongs to; omitted for the organization's own resources

Only for the resource's owner

The customer, when QBitFlow has one (named by the checkout, found by its customerReference, or recorded from the details the customer gave); omitted otherwise

Only for the resource's owner

The merchant's reference of the customer, as the checkout was given it (customerReference), whether or not QBitFlow has a customer with it; omitted otherwise

Only for the resource's owner

The customer, named (merchant only, API reads): who paid, even once deleted. Omitted without one

Only for the resource's owner

What its customer had to do before (absent: nothing)

Its id (sub@…): the checkout session's

A prefixed id (pay@…, sub@…)

The merchant's reference for the subscription (an order or customer id), set when creating its checkout. Only for the merchant: never in the public reads by uuid (GET /hosted/transactions/:txUuid)

Only for the resource's owner

Its last change (a bill, a status, its metadata)

The subscriber's wallet: the one it bills. Absent when unknown (a trial not confirmed yet may have none)

The wallet its bills pay: the merchant's (or, while the organization holds a member's funds, the organization's)

Its product (GET /products/:uuid). Absent without one

The hash of the transaction that created the subscription on-chain. Absent until then (a trial, until its customer confirms it)

The currency (token) billed, written as the currency object under currency (GET /currencies/:id)

Billing interval in seconds, as on-chain (e.g. 2592000 = 30 days). Written as a types.Duration in responses and webhooks (e.g. {"value": 1, "unit": "months"})

SubscriptionStatus (status) is where it stands: trial, trialExpired, active, pastDue, paused, stopped or cancelled. Every change sends subscription.statusChanged. Don't grant access from it: grant access while now < accessUntil (docs/api/guides/subscriptions.md § Access)

ActionRequired is what its customer must do, if anything (absent: nothing): topUpAllowance (the allowance covers about one more bill at most), raiseMaximum (a bill waits for a new maximum per period), confirmTrial (the trial ended unconfirmed). Every change (set, changed or cleared) sends subscription.actionRequiredChanged

CurrentPeriodEnd is the paid-through date. A trial: its end. active, paused, stopped: the end of the period paid for (the next bill's due date). pastDue: the start of the unpaid period (past). cancelled: when it was cancelled, or the end of its last paid period if that came first. For access, read accessUntil: an active subscription is renewed a few minutes after this date

AccessUntil is when access ends: grant it while now < accessUntil, whatever the status. An active subscription: currentPeriodEnd plus 1 hour, since its renewal is billed within minutes of its due date (a subscriber whose bill is on its way keeps access; a failed bill sets pastDue). Every other status: currentPeriodEnd

PriceUSD is the price per period the customer subscribed at, in USD (a decimal string, e.g. "9.99"), locked at signup (a free trial's too): every bill charges it and its lines (fees), converted to the token at the bill's price. A later change of the product's price applies to new subscribers only. Never "0"

Fees is what its checkout added to the price, line by line, as the customer saw them (a tax, shipping, the processing fee when the customer pays it), locked at signup with the price: every bill charges priceUsd plus these lines. [] without any

AllowanceStatus (allowance) is what the subscriber's wallet still lets QBitFlow bill, and the most one bill may charge, at today's price. Absent during a free trial (nothing signed yet)

When it was last billed. Absent before its first bill (a trial)

When its next bill is due (a trial: when it ends; stopped: when it is cancelled). Absent once cancelled

When it was cancelled (absent until then, and for subscriptions cancelled before it was recorded)

Why it stopped or was cancelled: customer, merchant, billingFailed, trialNotConverted, merchantClosed or inactiveOnChain. Absent while it runs (and for subscriptions cancelled before it was recorded)

MinimumCancellationDate (cancellableAt) is the earliest its customer may cancel it (the checkout's minPeriods). Absent when they may cancel it any time

Metadata is the merchant's own key-value data: its checkout session's, copied when the subscription was created, then changed with PATCH /subscriptions/:uuid (merged). {} when none. Only for the merchant (API and webhooks)

Only for the resource's owner

ManagementPageLink is the subscription's page for its customer: where they top up its allowance, raise its maximum, pause, resume or cancel it, and confirm a trial. Share it with them (an email, the merchant's account page)

Whether this is test data (testnets) or live data

Member the resource belongs to; omitted for the organization's own resources

Only for the resource's owner

The customer, when QBitFlow has one (named by the checkout, found by its customerReference, or recorded from the details the customer gave); omitted otherwise

Only for the resource's owner

The merchant's reference of the customer, as the checkout was given it (customerReference), whether or not QBitFlow has a customer with it; omitted otherwise

Only for the resource's owner

The customer, named (merchant only, API reads): who paid, even once deleted. Omitted without one

Only for the resource's owner

insufficientBalance, allowanceExhausted, approvalRevoked, maxAmountExceeded or other

The charge's error code (errors), e.g. insufficient_funds, insufficient_allowance

The bill that failed: the uuid its subscription.billed has once it is paid (sub-hist@…)

The bill, in USD (a decimal string): the price the customer subscribed at and its lines (fees)

This bill's failed attempts so far, this one included (maxAmountExceeded spends none)

Attempts left: retried 1, 3, 5 and 7 days after the bill's first failed attempt (at least a day apart), and at once when the customer raises their allowance. 0: this was the last; the subscription (still pastDue here) is cancelled next (subscription.statusChanged)

When the bill is tried again at the latest (maxAmountExceeded: when it stops waiting for a new maximum); absent after the last attempt

Its id (sub@…): the checkout session's

A prefixed id (pay@…, sub@…)

The merchant's reference for the subscription (an order or customer id), set when creating its checkout. Only for the merchant: never in the public reads by uuid (GET /hosted/transactions/:txUuid)

Only for the resource's owner

Its last change (a bill, a status, its metadata)

The subscriber's wallet: the one it bills. Absent when unknown (a trial not confirmed yet may have none)

The wallet its bills pay: the merchant's (or, while the organization holds a member's funds, the organization's)

Its product (GET /products/:uuid). Absent without one

The hash of the transaction that created the subscription on-chain. Absent until then (a trial, until its customer confirms it)

The currency (token) billed, written as the currency object under currency (GET /currencies/:id)

Billing interval in seconds, as on-chain (e.g. 2592000 = 30 days). Written as a types.Duration in responses and webhooks (e.g. {"value": 1, "unit": "months"})

SubscriptionStatus (status) is where it stands: trial, trialExpired, active, pastDue, paused, stopped or cancelled. Every change sends subscription.statusChanged. Don't grant access from it: grant access while now < accessUntil (docs/api/guides/subscriptions.md § Access)

ActionRequired is what its customer must do, if anything (absent: nothing): topUpAllowance (the allowance covers about one more bill at most), raiseMaximum (a bill waits for a new maximum per period), confirmTrial (the trial ended unconfirmed). Every change (set, changed or cleared) sends subscription.actionRequiredChanged

CurrentPeriodEnd is the paid-through date. A trial: its end. active, paused, stopped: the end of the period paid for (the next bill's due date). pastDue: the start of the unpaid period (past). cancelled: when it was cancelled, or the end of its last paid period if that came first. For access, read accessUntil: an active subscription is renewed a few minutes after this date

AccessUntil is when access ends: grant it while now < accessUntil, whatever the status. An active subscription: currentPeriodEnd plus 1 hour, since its renewal is billed within minutes of its due date (a subscriber whose bill is on its way keeps access; a failed bill sets pastDue). Every other status: currentPeriodEnd

PriceUSD is the price per period the customer subscribed at, in USD (a decimal string, e.g. "9.99"), locked at signup (a free trial's too): every bill charges it and its lines (fees), converted to the token at the bill's price. A later change of the product's price applies to new subscribers only. Never "0"

Fees is what its checkout added to the price, line by line, as the customer saw them (a tax, shipping, the processing fee when the customer pays it), locked at signup with the price: every bill charges priceUsd plus these lines. [] without any

AllowanceStatus (allowance) is what the subscriber's wallet still lets QBitFlow bill, and the most one bill may charge, at today's price. Absent during a free trial (nothing signed yet)

When it was last billed. Absent before its first bill (a trial)

When its next bill is due (a trial: when it ends; stopped: when it is cancelled). Absent once cancelled

When it was cancelled (absent until then, and for subscriptions cancelled before it was recorded)

Why it stopped or was cancelled: customer, merchant, billingFailed, trialNotConverted, merchantClosed or inactiveOnChain. Absent while it runs (and for subscriptions cancelled before it was recorded)