API Reference

Every endpoint, explained.

All endpoints require an X-API-Key header. Base URL: https://api.qbitflow.app/v1

Every request is authenticated with an X-API-Key header. Your API key determines both your identity and the mode of operation. With a test API key, all actions run on blockchain testnets and data (customers, products, transactions) is completely separate from live mode. Nothing crosses over.

Acting on behalf of a user

On-Behalf-OfOptional

Running a marketplace? You don't need to create and store a separate API key for every user. Send a single organization-level key and add the On-Behalf-Of header with the target user's ID. The request is then executed as that user — funds route to their wallet and your platform fee is applied — exactly as if you had used their own key.

X-API-Key: <your-organization-api-key>

On-Behalf-Of: 31

The official SDKs expose this as .onBehalfOf(userId) on any service (e.g. client.oneTimePayments.onBehalfOf(123).getAll()). It returns a scoped copy of the service, so your base client keeps operating at the organization level.

Requires an organization (admin/owner) key, and the target user must belong to your organization. Sending it with a regular user key fails with 403.
Works for any user-scoped action — checkouts, products, transactions, API keys, and more.
This is the recommended approach. Per-user API keys still work if you prefer them (see API Keys below).

Products

POST/product

Create a product

Prices are set in USD - QBitFlow automatically converts it to crypto at checkout using real-time exchange rates.

Validation: name is 2–100 characters and description is 2–500 characters (letters, numbers and spaces); price is in USD and must be ≥ 0.

Parameters

name: Required. 2–100 characters.
description: Required. 2–500 characters.
price: Required. In USD, must be ≥ 0.
reference: Optional - link to your existing product. If not provided, a default reference will be generated.

Header: X-API-Key: <your-api-key>

Request body

GET/product

Get all products

Header: X-API-Key: <your-api-key>

GET/product/id/{id}

Get a product by ID

Header: X-API-Key: <your-api-key>

GET/product/reference/{reference}

Get a product by reference

Header: X-API-Key: <your-api-key>

PUT/product/{id}

Update a product

name, description and price are all required and replace the current values. Same constraints as on create: name 2–100 chars, description 2–500 chars, price in USD ≥ 0.

Header: X-API-Key: <your-api-key>

Request body

DELETE/product/{id}

Delete a product

Header: X-API-Key: <your-api-key>

Users

POST/user

Create a user

Requires admin or owner role.

No password is set here. Provisioned users set their own password (and connect their wallet) through the claim flow — see 'Create a claim request' below.

Parameters

name / lastName: Required. 2–100 characters (letters, numbers and spaces).
email: Required. Must be a valid email address.
role: Required. Either 'user' or 'admin'.
organizationFeeBps: The organization fee in basis points (bps) that will be applied to transactions made by this user (0 to 5000 = 0% to 50%). Optional, defaults to 0.

Header: X-API-Key: <your-api-key>

Request body

GET/user

Get Me

Returns the user associated with the API key.

Header: X-API-Key: <your-api-key>

GET/user/all

Get all users

Requires admin or owner role.

Header: X-API-Key: <your-api-key>

GET/user/id/{id}

Get a user by ID

Requires admin or owner role.

Header: X-API-Key: <your-api-key>

GET/user/email/{email}

Get a user by email

Requires admin or owner role.

Header: X-API-Key: <your-api-key>

PUT/user/{id}

Update a user

If the API key belongs to the user, the organization fee is ignored.

If the API key belongs to an admin or owner, the organization fee is updated.

Password is optional — if not provided, the password is not changed.

Parameters

password: Optional. 8–128 characters. If omitted, the password is left unchanged.
organizationFeeBps: The organization fee in basis points (bps) that will be applied to transactions made by this user (0 to 5000 = 0% to 50%).

Header: X-API-Key: <your-api-key>

Request body

DELETE/user/{id}

Delete a user

Requires admin or owner role.

Header: X-API-Key: <your-api-key>

Claim (Account & Funds)

POST/user/claim/request

Create a claim request

Creates a claim request (invite link) for a user within the organization. The user follows this link to set up their password and connect their wallet, after which accumulated earnings are transferred to them.

Requires admin or owner role.

Header: X-API-Key: <your-api-key>

Request body

GET/user/claim/request/{userID}

Get an existing claim request

Returns the existing claim link for a user without creating a new one. Useful to retrieve the link if it was previously generated and needs to be resent.

Requires admin or owner role.

Header: X-API-Key: <your-api-key>

GET/user/claim/funds

Get claim funds

Returns all active claim fund entries for the organization — funds that need to be transferred to users who have claimed their accounts.

Header: X-API-Key: <your-api-key>

GET/user/claim/funds/test-trigger/{userID}

Test trigger claim funds

Triggers a test claim fund entry for a user by computing the total amount from ledger entries. In production, this is done automatically every hour. This endpoint allows testing the claim fund process manually.

Requires admin or owner role.

Only works for test mode.

Header: X-API-Key: <your-api-key>

API Keys

POST/api-key

Create an API key

If the API key belongs to a user, creates an API key for that user.

If the API key belongs to an admin or owner, creates an API key for the specified userId (within the same organization).

You usually don't need per-user keys anymore: an organization-level (admin/owner) key can act as any user with the On-Behalf-Of header. See Authentication. Per-user keys remain fully supported if you prefer them.

Requires a JWT-authenticated (dashboard) session — API keys cannot be created with another API key.

Parameters

name: Required. 3–30 characters (letters, numbers and spaces).
userId: The user to create the key for. Ignored for user-level keys (uses the caller); required for admin/owner keys.
expiresAt: Optional ISO timestamp. If null, the key never expires.
test: Whether this is a test-mode key. Defaults to false (live).

Header: X-API-Key: <your-api-key>

Request body

GET/api-key

Get all my API keys

Header: X-API-Key: <your-api-key>

GET/api-key/user/{id}

Get API keys for a user

Returns all API keys for a specific user. Admin only.

Requires admin or owner role.

Header: X-API-Key: <your-api-key>

DELETE/api-key/{id}

Delete an API key

Requires a JWT-authenticated (dashboard) session — API keys cannot be deleted with another API key.

Header: X-API-Key: <your-api-key>

Customers

POST/customer/

Create a customer

Parameters

name / lastName: Required. 2–100 characters (letters, numbers and spaces).
email: Required. Must be a valid email address.
phoneNumber: Optional
address: Optional
reference: Optional - link to your existing customer

Header: X-API-Key: <your-api-key>

Request body

GET/customer/all

Get all customers

Query parameters

cursor: The cursor (UUID) to retrieve the next page of results.
limit: The number of customers to retrieve per page.

Header: X-API-Key: <your-api-key>

GET/customer/uuid/{uuid}

Get a customer by UUID

Header: X-API-Key: <your-api-key>

GET/customer/email/{email}

Get a customer by email

Header: X-API-Key: <your-api-key>

GET/customer/reference/{reference}

Get a customer by reference

Looks up a customer by the reference you assigned when creating it. Useful to resolve the customer's UUID from your own identifier.

Header: X-API-Key: <your-api-key>

PUT/customer/{uuid}

Update a customer

Parameters

phoneNumber: Optional
address: Optional

Header: X-API-Key: <your-api-key>

Request body

DELETE/customer/uuid/{uuid}

Delete a customer

Header: X-API-Key: <your-api-key>

One-Time Payments

POST/transaction/session-checkout/new/payment

Create a one-time payment (without a product)

Creates a payment session from scratch. Customer information can be provided with the request or collected during the payment process.

Marketplace: to credit one of your users, add the On-Behalf-Of: <userId> header to your organization-level (admin/owner) key. The checkout is created as that user, so funds route to their wallet and your platform fee is applied — no per-user API key required. See Authentication.

Parameters

successUrl and cancelUrl: Optional - to allow redirecting the customer to the appropriate page after the payment process. If not provided, the customer will be redirected to a default page.
customerUUID: If customerUUID is provided and matches an existing customer, that customer's information will be pre-filled during the checkout process. If not provided or if it doesn't match any existing customer, the checkout process will allow entering new customer information.
customerReference: Optional alternative to customerUUID — the reference you assigned to the customer. Provide either customerUUID or customerReference to identify an existing customer; there's no need to store QBitFlow's customer UUID on your side.
reference: Optional — your own reference for the transaction (e.g. your internal order or invoice ID). It's stored on the resulting payment or subscription so you can retrieve it later by reference via the get-by-reference endpoints, instead of storing QBitFlow's UUID.

Header: X-API-Key: <your-api-key>

Request body

POST/transaction/session-checkout/new/payment

Create a one-time payment (from a product)

Creates a payment session from an existing product. The product can be selected by productId or by productReference (provide one). Customer information can be provided with the request or collected during the payment process.

Parameters

successUrl and cancelUrl: Optional - to allow redirecting the customer to the appropriate page after the payment process. If not provided, the customer will be redirected to a default page.
productId: The ID of the product to charge for. Provide either productId or productReference to select the product (not both).
productReference: The reference you assigned to the product — an alternative to productId. Provide either productId or productReference (not both); this way there's no need to store QBitFlow's product ID on your side.
customerUUID: The UUID of an existing customer — an alternative to customerReference. If provided and it matches an existing customer, that customer's information will be pre-filled during the checkout process. If neither customerUUID nor customerReference is provided (or no match is found), the checkout process will allow entering new customer information.
customerReference: The reference you assigned to the customer — an alternative to customerUUID. Provide either customerUUID or customerReference (not both); this way there's no need to store QBitFlow's customer UUID on your side.
reference: Optional — your own reference for the transaction (e.g. your internal order or invoice ID). It's stored on the resulting payment or subscription so you can retrieve it later by reference via the get-by-reference endpoints, instead of storing QBitFlow's UUID.

Header: X-API-Key: <your-api-key>

Request body

GET/transaction/session-checkout/{uuid}Public

Retrieve session checkout details

Returns the session checkout data. The response can be either a TransactionData (for one-time payments) or a SubscriptionData (for subscriptions).

Query parameters

closeToExpireError: Optional boolean — whether to return an error if the session is close to expiration (default: true).

Public endpoint — no X-API-Key header required.

Transaction Info

GET/transaction/payments

Get all one-time payments

Get all one-time payment transactions for the organization, with pagination support.

Query parameters

cursor: The cursor (UUID) to retrieve the next page of results.
limit: The number of transactions to retrieve per page.

Header: X-API-Key: <your-api-key>

GET/transaction/payments/combined

Get all payments (combined)

Get all transactions (one-time payments and subscription payments) for the organization, with pagination support.

Query parameters

cursor: The cursor (UUID) to retrieve the next page of results.
limit: The number of transactions to retrieve per page.

Header: X-API-Key: <your-api-key>

GET/transaction/payment/{paymentUUID}

Get a payment by UUID

Header: X-API-Key: <your-api-key>

GET/transaction/payment/reference/{paymentReference}

Get a payment by reference

Looks up a payment by the reference you assigned when creating it. Resolves QBitFlow's payment UUID from your own order or invoice identifier, so you don't need to store the UUID on your side.

Header: X-API-Key: <your-api-key>

GET/transaction/customer/{transactionUUID}

Get customer for a transaction

Returns the customer information associated with a transaction.

Header: X-API-Key: <your-api-key>

Subscriptions

POST/transaction/session-checkout/new/subscription

Create a subscription

Marketplace: to credit one of your users, add the On-Behalf-Of: <userId> header to your organization-level (admin/owner) key. The subscription is created as that user, so funds route to their wallet and your platform fee is applied — no per-user API key required. See Authentication.

Parameters

successUrl and cancelUrl: Optional - to allow redirecting the customer to the appropriate page after the payment process. If not provided, the customer will be redirected to a default page.
productId: The ID of the product to subscribe to. Provide either productId or productReference to select the product (not both).
productReference: The reference you assigned to the product — an alternative to productId. Provide either productId or productReference (not both); this way there's no need to store QBitFlow's product ID on your side.
customerUUID: The UUID of an existing customer — an alternative to customerReference. If provided and it matches an existing customer, that customer's information will be pre-filled during the checkout process. If neither customerUUID nor customerReference is provided (or no match is found), the checkout process will allow entering new customer information.
customerReference: The reference you assigned to the customer — an alternative to customerUUID. Provide either customerUUID or customerReference (not both); this way there's no need to store QBitFlow's customer UUID on your side.
reference: Optional — your own reference for the transaction (e.g. your internal order or invoice ID). It's stored on the resulting payment or subscription so you can retrieve it later by reference via the get-by-reference endpoints, instead of storing QBitFlow's UUID.
minPeriods: Optional - minimum number of periods the user must subscribe for (e.g., 3 months).

Header: X-API-Key: <your-api-key>

Request body

POST/transaction/session-checkout/new/subscription

Create a subscription with trial period

Parameters

successUrl and cancelUrl: Optional - to allow redirecting the customer to the appropriate page after the payment process. If not provided, the customer will be redirected to a default page.
productId: The ID of the product to subscribe to. Provide either productId or productReference to select the product (not both).
productReference: The reference you assigned to the product — an alternative to productId. Provide either productId or productReference (not both); this way there's no need to store QBitFlow's product ID on your side.
customerUUID: The UUID of an existing customer — an alternative to customerReference. If provided and it matches an existing customer, that customer's information will be pre-filled during the checkout process. If neither customerUUID nor customerReference is provided (or no match is found), the checkout process will allow entering new customer information.
customerReference: The reference you assigned to the customer — an alternative to customerUUID. Provide either customerUUID or customerReference (not both); this way there's no need to store QBitFlow's customer UUID on your side.
reference: Optional — your own reference for the transaction (e.g. your internal order or invoice ID). It's stored on the resulting payment or subscription so you can retrieve it later by reference via the get-by-reference endpoints, instead of storing QBitFlow's UUID.

Header: X-API-Key: <your-api-key>

Request body

GET/transaction/subscription/{subscriptionUUID}

Get subscription details

Header: X-API-Key: <your-api-key>

GET/transaction/subscription/reference/{subscriptionType}/{subscriptionReference}

Get subscription details by reference

Looks up a subscription by the reference you assigned when creating it. Resolves QBitFlow's subscription UUID from your own identifier, so you don't need to store the UUID on your side.

Parameters

subscriptionType: Required - the type of subscription to look up: either subscription or payAsYouGo.
subscriptionReference: Required - the reference you assigned to the subscription when creating it.

Header: X-API-Key: <your-api-key>

GET/transaction/subscription/history/{subscriptionUUID}Public

Get subscription payment history

Public endpoint — no X-API-Key header required.

GET/transaction/subscription/processing/force-cancel/{subscriptionUUID}

Force cancel a subscription

Force cancels a subscription. Normally a subscription is cancelled by the user signing a message, but the merchant can bypass this to immediately cancel a subscription for any reason (e.g., suspicious activity, user request, etc.).

Header: X-API-Key: <your-api-key>

GET/transaction/subscription/processing/execute-billing/{subscriptionUUID}

Test subscription billing

Live subscriptions are billed automatically based on their billing cycle. This endpoint allows you to simulate the billing process for test subscriptions, which can be useful for testing your webhook handling and subscription management logic.

This endpoint can only be used with test subscriptions. Attempting to use it with a live subscription will result in an error.

When you call this endpoint for a test subscription, it will immediately process the next billing cycle for that subscription. This includes charging the customer and generating the appropriate webhook events as if the billing cycle had naturally occurred.

Use this endpoint to verify that your system correctly handles subscription billing events, such as successful payments, failed payments, and subscription renewals.

Header: X-API-Key: <your-api-key>

Refunds

GET/transaction/refunds/by-transaction/{transactionUUID}Public

Get refund by transaction UUID

Returns the refund entry associated with a transaction.

Public endpoint — no X-API-Key header required.

GET/transaction/refunds/all

Get all active refunds

Returns all active refund entries for the organization.

Header: X-API-Key: <your-api-key>

GET/transaction/refunds/all/inactive

Get all inactive refunds

Returns all inactive (processed) refund entries for the organization, with pagination support.

Query parameters

cursor: The cursor (UUID) to retrieve the next page of results.
limit: The number of refunds to retrieve per page.

Header: X-API-Key: <your-api-key>

Transaction Status

GET/transaction/statusPublic

Get transaction status

Returns the current status of a transaction (payment, subscription, or allowance processing).

A WebSocket version is also available at /transaction/status/ws with the same query parameters for real-time updates.

Query parameters

txUUID: Required - The UUID of the transaction to monitor.
txType: Required - The type of the transaction status to monitor (e.g., "payment", "subscription", "allowance").

Public endpoint — no X-API-Key header required.

Accounting

GET/accounting/export

Export accounting data

Exports accounting data for the organization within a date range, in CSV or JSON format.

Query parameters

from: Required - Start date (date format, e.g., 2024-01-01).
to: Required - End date (date format, e.g., 2024-12-31).
format: Required - Export format: "csv" or "json".

Header: X-API-Key: <your-api-key>

Utilities

GET/utils/all-available-currenciesPublic

Get all available currencies

Returns every supported currency — both native/main currencies (e.g. ETH, SOL) and tokens (e.g. USDC), across all chains. Use this to resolve the currency ids returned in availableCurrencies on a session checkout, or in currencyId on payments and subscriptions.

Query parameters

test: Optional boolean. When true, returns testnet currencies instead of mainnet ones (default: false).

Public endpoint — no X-API-Key header required.

GET/utils/all-main-currenciesPublic

Get all main currencies

Returns only the main (native) currencies — one per supported chain (e.g. ETH, SOL) — without the tokens that settle on them. Useful for chain pickers.

Query parameters

test: Optional boolean. When true, returns testnet currencies instead of mainnet ones (default: false).

Public endpoint — no X-API-Key header required.

Webhooks

POSTDashboard → Settings → Webhooks

Receiving webhooks (setup)

Webhook endpoints are configured in the dashboard, not per session. Under Settings → Webhooks you set two independent URLs — one for the Transaction webhook and one for the Subscription webhook — each with a separate Test and Live configuration. QBitFlow sends a POST request to the matching endpoint whenever a relevant event occurs. The two webhooks are documented separately below.

Transaction webhook — fires when a checkout you created is completed by the customer (a one-time payment is paid, or a new subscription is started). See 'Transaction webhook' below.

Subscription webhook — fires over the life of an existing subscription: on a status change (e.g. active → past_due, active → cancelled) and on each successful billing. See 'Subscription webhook' below. Use this instead of polling subscription status on a cron.

Test vs Live: Test-mode events are delivered to the Test endpoints, live-mode events to the Live endpoints. The 'Test the endpoint' button in the dashboard sends a probe request (see TEST_WEBHOOK_ID below).

Every delivery includes the headers X-Webhook-Signature-256, X-Webhook-Timestamp, and X-Webhook-ID. Always verify the signature before processing (see 'Verify webhook signature').

TEST_WEBHOOK_ID = "test-webhook-id". When the dashboard 'Test the endpoint' action reaches your server, the X-Webhook-ID header equals this value. The probe carries a fake payload that is not a real event — if X-Webhook-ID matches TEST_WEBHOOK_ID, return HTTP 200 immediately and skip normal payload processing. The official SDKs expose this constant and header name for you.

Always return HTTP 200 to acknowledge receipt. Any non-2xx response causes QBitFlow to retry delivery.

POSTPOST → your Transaction webhook URL

Transaction webhook

Fires when a checkout you created is completed by the customer. Two cases trigger it: (1) you created a one-time payment checkout and the customer paid; (2) you created a subscription checkout and the customer completed it — in that case the first billing already happened, so the customer has been charged for the first period. The shape of the session field depends on txType.

txType is the top-level transaction type: 'payment' for a one-time payment, 'createSubscription' for a new subscription. (Note: session.txType uses the short form — 'payment' / 'subscription'.)

session is the checkout data, sent as-is. For 'payment' it is a TransactionData; for 'createSubscription' it is a SubscriptionData (a TransactionData plus the subscription fields).

session.reference is the reference you set when creating the transaction — use it to link the event back to your own order/invoice.

managementPageLink links to the transaction's management page — you can redirect the user there after receiving the webhook.

POSTPOST → your Subscription webhook URL

Subscription webhook

Fires over the life of an existing subscription. Two cases trigger it: (1) a status change that needs your input — the subscription was cancelled, is running low on funds, etc.; (2) a billing event — an active subscription renewed for a new period, so you can record a subscription-history entry. The shape of the data field depends on type.

type is 'status_transition' for a status change, or 'billing' for a successful renewal.

data is a SubscriptionStatusTransition when type is 'status_transition', or a SubscriptionHistory when type is 'billing'.

subscriptionReference is the reference you set when creating the subscription — use it to link the event back to your own order/invoice (present when you provided one).

POST/webhooks/verify

Verify webhook signature

The payload must be exactly the same as the one received in the webhook request. Read the raw body of the request received on your webhook endpoint and use it as the payload — do not parse it as JSON and re-stringify it, as formatting changes will cause signature verification failure.

The official SDKs provide a webhooks.verify(payload, signature, timestamp) helper that performs this check for you.

Header: X-API-Key: <your-api-key>

Request body