API Reference

Every endpoint, explained.

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

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.

Products

POST/product

Create a product

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

Parameters

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

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.

Parameters

role: The role can be 'user' or 'admin'. Required.
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

organizationFeeBps: The organization fee in basis points (bps) that will be applied to transactions made by this user (0 to 1000).

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).

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

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

Customers

POST/customer/

Create a customer

Parameters

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.

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}

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).

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

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

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}

Get subscription payment history

This is a public endpoint — no authentication required.

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

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}

Get refund by transaction UUID

Returns the refund entry associated with a transaction. This is a public endpoint.

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

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/status

Get transaction status

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

This is a public endpoint — no authentication required.

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").

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

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>

Webhooks

POSTDashboard → Settings → Webhooks

Receiving webhooks (endpoints)

Webhook endpoints are configured in the dashboard, not per session. Under Settings → Webhooks you set two independent URLs, each with a separate Test and Live configuration. QBitFlow sends a POST request to the matching endpoint whenever a relevant event occurs.

Transaction webhook — fires on individual payment events (a payment completes, or a new subscription is created). Payload: SessionWebhookResponse.

Subscription status webhook — fires whenever an existing subscription changes state (e.g. active → low_on_funds, active → cancelled). Payload: SubscriptionStatusTransitionWebhook. 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.

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