Held funds and their release

What you owe each held seller, line by line. Paid out in one transfer, signed from your dashboard.

A held seller's sales pay your organization's wallet, and QBitFlow records what you owe them: their share, your commission withheld. It stays there until you release it.

  1. Held in your walletA saleOwed to the seller: their share, your commission withheld
  2. A negative lineA refund, maybeSent from your wallet; what you owe drops
  3. heldFunds.released ✓You releaseEverything held, in one transfer, signed with your wallet
  4. Paid directlyYou trust themTheir new payments go straight to their wallet

What you hold

Read members' held funds

members-held-funds.sh

# What the organization holds for its members (their payments while untrusted), the longest held# first. One member's lines: GET /members/$MEMBER_UUID/held-funds.curl https://api.qbitflow.app/v2/members/held-funds \  -H "X-API-Key: $QBITFLOW_API_KEY"# 200: [ { "userUuid": "…", "totalAmount": 98.35, "count": 2, "oldestAt": "…" } ]
// What the organization holds for its members (their payments while untrusted), the longest// held first.const all = await client.members.listHeldFunds();for (const owed of all) {	console.log(`${owed.userUuid}: ${owed.totalUsd} USD owed over ${owed.count} lines`);} const held = await client.members.getHeldFunds(memberUuid);for (const ledger of held.ledgers) {	// owed: what the line counts for in a release (negative for a refund).	console.log(		`  ${ledger.type} ${ledger.owed} ${ledger.currency.symbol} (${ledger.owedUsd} USD)`	);}console.log(`held for this member: ${held.totalUsd} USD`);
# Every member you hold funds for, the longest held first.for summary in client.members.list_held_funds():    print(summary.user_uuid, f"{summary.total_usd} USD over {summary.count} lines") held = client.members.get_held_funds(member_uuid)  # one member, line by lineprint(f"owed to the seller: {held.total_usd} USD over {len(held.ledgers)} lines")
// What the organization holds for its members (their payments while untrusted).// The longest held first.all, err := client.Members.ListHeldFunds(ctx)if err != nil {	log.Fatal(err)}for _, s := range all {	fmt.Printf("%s: %s USD over %d lines\n", s.UserUUID, s.TotalUSD, s.Count)} held, err := client.Members.GetHeldFunds(ctx, memberUUID)if err != nil {	log.Fatal(err)}fmt.Printf("owed to %s: %s USD over %d lines\n", memberUUID, held.TotalUSD, len(held.Ledgers))
foreach ($client->members->listHeldFunds() as $owed) { // every member you owe, the longest held first	echo "{$owed->userUuid}: {$owed->totalUsd} USD over {$owed->count} lines\n";} $held = $client->members->getHeldFunds($memberUuid);printf("Owed to %s: %s USD over %d lines\n", $memberUuid, $held->totalUsd, count($held->ledgers));

The sellers you hold funds for, longest held first, each with its totalUsd. One seller's detail is ledgers: a line per payment held, oldest first, with what you still owe for it (owedMinUnits, owedUsd). A refund of a held payment is a negative line of its own.

What the seller sees

The same, for their own space: on their dashboard's Payouts page, with their own key, or from yours acting for them.

Read your own held funds (as a member)

members-own-held-funds.sh

# What the organization holds for the key's own space (a member's key, or On-Behalf-Of a member).# Empty for the organization.curl https://api.qbitflow.app/v2/held-funds \  -H "X-API-Key: $QBITFLOW_API_KEY"# 200: a HeldFunds
// With a member's key, or a client.onBehalfOf(memberUuid) client. Empty for the organization.const held = await client.members.getOwnHeldFunds();console.log(`held for me: ${held.totalUsd} USD over ${held.ledgers.length} lines`);
# With a member's key, or a client acting on behalf of the member.held = client.members.get_own_held_funds()print(f"held for me: {held.total_usd} USD over {len(held.ledgers)} lines")
// As the member: with their own key, or the organization's acting for them.own, err := client.OnBehalfOf(memberUUID).Members.GetOwnHeldFunds(ctx)if err != nil {	log.Fatal(err)}fmt.Printf("held for me: %s USD over %d lines\n", own.TotalUSD, len(own.Ledgers))
// With a member's key (or a client from $client->onBehalfOf($memberUuid)):$held = $client->members->getOwnHeldFunds();printf("Held for me: %s USD over %d lines\n", $held->totalUsd, count($held->ledgers));

Release it, from the dashboard

A release is a transfer from your wallet to the seller's, so your wallet signs it, in the dashboard. SDKs can't release yet.

From the contract · ledger.md § Releasing

  1. Held in your wallet: Each sale pays your organization's wallet; you owe the seller their share, your commission kept.
  2. You release, signed once: From the seller's page in the dashboard: pick a token, sign once with your organization's wallet.
  3. The seller's wallet: Everything held for them, at today's price, in one transfer to their wallet: heldFunds.released.
Where: Dashboard/Members/the seller/Held funds/Release. Releasing from the SDKs isn't available yet.
  • Everything held for that seller in this mode, whatever chain each sale was on: converted at today's price into the token you pick, sent on that token's chain, signed once.
  • The seller needs a wallet on that chain; yours must hold the amount.
  • Refunds cancel out what's held? Nothing to pay: the dashboard offers to close the held funds.

Once it confirms, those lines leave the held funds, QBitFlow emails the seller what they received, and the seller's heldFunds.released arrives:

heldFunds.released· the body your endpoint receives

{  "createdAt": "2026-10-01T12:00:00Z",  "data": {    "amount": "98.9068",    "chain": "BASE",    "currency": {      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",      "chain": "BASE",      "code": "BASE:USDC",      "decimals": 6,      "id": 8,      "mainCurrencyId": 3,      "name": "USD Coin",      "symbol": "USDC",      "test": false    },    "ledgers": […],    … 13 more fields  },  "id": "evt_620352e2-0285-52e8-adc1-64a9774278c1",  "test": false,  "type": "heldFunds.released",  "userUuid": "019eca82-5680-7b00-8000-0000000000b1",  "version": "v2"}
The contract's example (webhooks.md § Examples)
  1. data.chain: That token's chain, where the transfer was sent.
  2. data.currency: The token you picked to pay them in.
  3. userUuid: The seller's: it's their event.

Its ledgers (folded above) are the lines it settled.

Check it

Pay a held test seller's checkout: it's in what you hold, and in their Held funds in Dashboard/Members. Release and sign: their held funds empty, and heldFunds.released arrives with their userUuid.