API Reference

Complete API endpoint reference for QBitFlow. All endpoints require an X-API-Key header.

Your API key determines both your identity and the mode of operation. If you use a Test API key, all actions are performed in test mode — payments are processed on blockchain testnets, and all data (customers, products, transactions, etc.) is completely separate from live mode. Nothing created in test mode will appear in live mode, and vice versa.

Base url: https://api.qbitflow.app/v1

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

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>

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.
webhookUrl: Optional - to allow receiving real-time notifications about the payment status. If not provided, no webhooks will be sent for this transaction.
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.

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. 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.
webhookUrl: Optional - to allow receiving real-time notifications about the payment status. If not provided, no webhooks will be sent for this transaction.
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.

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/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.
webhookUrl: Optional - to allow receiving real-time notifications about the payment status. If not provided, no webhooks will be sent for this transaction.
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.
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.
webhookUrl: Optional - to allow receiving real-time notifications about the payment status. If not provided, no webhooks will be sent for this transaction.
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.

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

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.

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

Request Body