Wallets and balances

A wallet is the per-recipient ledger inside Finance. One wallet per (ownerType, ownerId) pair — typically one per customer, but you can also have wallets for users, vendors, affiliates, or any other addressable principal.

Wallet identity

Field	Meaning
ownerType	The collection the owner lives in: customer, user, affiliate, etc.
ownerId	The owner's sk (org-scoped key).
currency	ISO 4217 code. Defaults to USD.
name	Display name — typically the owner's full name or email.
email	Owner email, copied for reporting.
status	active, frozen, closed.

The wallet's sk is the canonical wallet ID used everywhere else.

Creating a wallet

You rarely create wallets explicitly — most flows use the get-or-create endpoint, which is idempotent on (ownerType, ownerId).

curl -X POST https://appengine.appmint.io/finance/wallets/get-or-create \
  -H "orgid: $ORG" \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "ownerType": "customer",
    "ownerId": "cust_abc123",
    "email": "[email protected]",
    "name": "Alice Doe"
  }'

If a wallet already exists for that pair, you get the existing record. No collision, no duplicate.

For explicit creation:

Same body as get-or-create, plus an optional currency. Errors if the pair already has a wallet.

Reading a wallet

The customer-side endpoint. Resolves the calling customer, finds (or creates) their wallet, and returns it with the full transaction list and a summary block. Use this from a creator dashboard.

Staff endpoint. Returns wallet + transactions for any wallet in the org.

Lookup by owner without knowing the wallet ID.

The three balances

A wallet carries three numbers, and you should know which is which.

Balance	Meaning	Pay-out-able?
Available	Funds settled, cleared of any holds, ready to withdraw.	Yes
Pending	Credits awaiting clearance — held for dispute window, security review, or scheduled release.	No
Held	Subset of pending under an active hold record (reason, expiresAt).	No

When a customer requests a payout, the system reserves from available, not pending. Holds shift money from available to held; releases reverse the move. There is no separate "current" or "ledger" balance — only the three above.

Holds

Holds are useful when you credit a wallet eagerly but want to delay payout eligibility — for example, a 7-day clearing window after a sale.

{
  "reason": "deposit",
  "amount": 100.00,
  "expiresAt": "2026-05-02T00:00:00Z",
  "reference": "order-991",
  "notes": "7-day clearing"
}

reason accepts: dispute | chargeback | security | deposit | pending_review | other.

holdIndex is the zero-based index of the hold inside the wallet's holds array. Released funds move from held back to available.

Freezing a wallet

A frozen wallet rejects all credits, debits, and payout requests until it's unfrozen. Use this for compliance investigations or fraud reviews.

{
  "reason": "Suspicious activity — manual review",
  "frozenBy": "[email protected]",
  "unfreezeAt": "2026-05-01T00:00:00Z"
}

unfreezeAt is informational — there is no auto-unfreeze cron. Call:

To restore the wallet. The unfreezeAt from the freeze record is shown in admin UI but you must explicitly unfreeze.

Payout settings

Wallets carry per-wallet payout configuration: minimum payout amount, schedule (manual/weekly/monthly), and default method.

The body is open-ended — settings are stored on the wallet record and read by the payout flow. Common keys:

{
  "minimumPayout": 25.00,
  "schedule": "weekly",
  "scheduleDay": "friday",
  "defaultMethodId": "method_abc"
}

For customer self-service of the same fields:

Listing wallets

Filter with ownerType, status, page, pageSize. Returns wallets with a balance and transaction summary, but not the full transaction list — use the single-wallet endpoint for that.

Stats

Counts by status, total available across all wallets, total pending. Useful for an ops dashboard or as a pre-payout-batch sanity check.