All endpoints
Every operation in the wallet contract, in one list. This is the fastest way to find an endpoint by name, or to hand the whole surface to an agent.
Users and balances
Wallet users, their balances per account purpose, and their transaction history.
Resolve the calling user token to its wallet user
Resolves the calling user token to its wallet user.
Search and page the tenant's users (admin)
Search and page the tenant's users. Requires users:read and a machine or staff principal — a user token is refused forbidden (403) because listing everyone is not a self-read.
Create or attach a wallet user
Creates a wallet user, or attaches one to an identity you already have.
Fetch a wallet user
Fetches one wallet user. Requires users:read.
List a user's balances per account purpose
One row per account purpose and commodity, each with balance, held and available, as the tenant's ledger of record reports them; held is money reserved by an authorization that has not been captured.
A user's ledger history across cash and points
The user's own ledger entries across cash and points, newest first, each with the transaction it belongs to, its direction and its commodity.
Register the calling user's device for push notifications
Records a Firebase Cloud Messaging token so money events can reach the caller's device.
Set a business user's credit line (audited; API keys only)
Sets a business user's credit line, the floor below zero its cash account may go.
Top-ups
Money in, through a payment gateway. The wallet is credited only on verified confirmation.
The configured top-up gateways, for client UIs picking a rail
The top-up gateways this deployment has configured, each with the flow a client UI must drive (client_secret or redirect) and the currencies it accepts.
Start a top-up through a payment gateway
Starts a top-up and returns an intent. It does not credit the wallet.
Fetch a top-up intent
Fetches a top-up intent and its current status.
Ask the gateway for a pending top-up's current outcome
Reconciles one intent on demand: the gateway is asked what it thinks, and a terminal answer is applied through the same verified-confirmation path a webhook uses, so a credit can never happen twice.
Inbound payment-processor callback (processors only, never called by an integrator)
Inbound. This is where the payment processor tells WalletD that a top-up succeeded or failed; an integrator never calls it.
Transfers
Peer-to-peer movement inside the tenant loop.
Payments and refunds
Paying a merchant instantly or as an authorization hold, then capturing, voiding or refunding it.
Pay a merchant, instantly or as an authorization hold
Charges a wallet user and settles the merchant, in one balanced posting or not at all.
Fetch a payment
Fetches one payment with its captured and refunded totals, its fee, and any marketplace commission.
Capture an authorized payment, optionally partially
Captures an authorized payment. amount defaults to the full authorization; capturing less releases the remainder of the hold back to the payer in the same posting.
Release an authorized payment without capturing
Releases an authorized payment without taking any money; the whole hold returns to the payer and nothing settles.
Refund a captured payment back to the payer's wallet
Returns captured money to the payer's wallet as a contra posting: the original transaction is never rewritten, so both movements stay in the history.
Subscriptions
Recurring charge mandates, their lifecycle, and the dunning that follows a failed cycle.
Page the tenant's subscriptions (admin)
The tenant's subscriptions, optionally narrowed by user_id and status.
Create a recurring charge mandate
Records a recurring charge mandate. Creating one moves no money: the first charge runs at start_at (now when omitted) and the scheduler charges once per interval after that, retrying a failed perio...
Fetch a subscription
Fetches one subscription with its status, next charge time and retry count.
Pause charging
Stops charging without ending the mandate; nothing is billed while it is paused.
Resume a paused subscription; the period re-anchors at the resume time
Restarts a paused subscription. The period re-anchors at the resume time, so the subscriber is not billed for the pause and the next charge is a full interval away.
Cancel a subscription permanently
Ends the mandate permanently — a cancelled subscription cannot be resumed, and a new one has to be created instead.
Rewards and loyalty
Reward rules, the grants they produce, and converting points back into wallet cash.
Disable a reward rule; existing grants stand
Stops a rule being evaluated from now on.
List reward rules
Every reward rule the tenant has, including disabled ones, oldest first, each with its parameters, scope and caps.
Create a reward rule (cashback, accrual, or conversion)
Creates a cashback, accrual or conversion rule, scoped to merchants, categories or one offering, and capped per transaction and per user per day.
Convert points to wallet cash at the tenant rate
Burns loyalty points and credits the user's wallet cash at the tenant's active conversion rule, in one balanced posting.
List a user's reward grants, newest first
A user's reward grants, newest first, each naming the rule that made it and the transaction it credited.
Limits and tiers
Per-tier caps on money movement and the tier a user is assigned to.
The tenant's configured tier caps (admin)
The tenant's configured caps per tier: maximum balance, top-up per day and peer-to-peer per day.
Upsert one tier's caps (audited; admin)
Creates or replaces one tier's caps. Requires limits:manage and a machine or staff principal — a user token is refused admin_only (403).
Assign a user's limit tier (audited; admin)
Assigns a user to a limit tier and answers with the tier it replaced.
Merchants
Merchants and their settlement accounts.
Register a merchant with its settlement account
Registers a merchant and its settlement account so it can be paid.
Fetch a merchant
Fetches one merchant. Requires merchants:read; an unknown id gives merchant_not_found (404).
List settlement account entries
The merchant's settlement entries, newest first.
Catalog
Offerings, variants, categories and stock, owned by the ecosystem client that sells them.
Upload one image and get the URL to store on a profile or offering
Stores one image in the deployment's object store and answers with its public URL, which you then pass as logo_url or image_url on a separate profile or offering write; uploading alone changes noth...
The clients the caller may manage
A consumer gets the clients its organization memberships cover, which is how a founder finds their own client after onboarding.
Self-serve ecosystem client onboarding (org + merchant + profile)
Self-serve onboarding: creates the identity-provider organization, the merchant with its settlement account and the public profile in one call.
What this client sold, and what it kept
The client's own trading history: a summary (sales, gross, fees, marketplace commission, refunded and net, plus subscriber count) followed by a page of individual sales, newest first by created_at,...
Fetch a client (members and loop staff)
Fetches one client with its profile, status, commission override and the merchant it settles to.
Update the client's public identity
Replaces the client's public identity — display name, category, description and logo — as Explore shows it.
The client's own offerings, one page at a time
The client's own offerings in every status, with the merchant view of each variant: cost, markup, pricing mode and stock counts, none of which Explore ever shows a shopper.
Create a draft offering
Creates an offering as a draft; nothing reaches Explore until it is published.
One of the client's own offerings, any status, with its live variants
One of the client's own offerings in any status, with its live variants and the merchant-only pricing fields.
Edit an offering
A draft may change anything. A published item may be repriced, and the change is recorded in its price history.
Publish a draft offering to discovery
Moves a draft into discovery. This is the only client action that puts something in front of the loop's users, so it is the one that waits for approval: a client the platform has not made active is...
Archive an offering (draft or published)
Retires an offering, draft or published: it leaves discovery and can no longer be edited or bought.
Add a variant to an item
Adds a variant to a product, with its own option values, price or cost-plus markup, SKU and optional inventory tracking.
Edit a variant; a price change is recorded in history
Edits one variant. A price change is written to the client's price history with the actor that made it, so a shopper's disputed price can be explained later.
Retire a variant (a product keeps at least one)
Retires one variant. A product keeps at least one live variant, so archiving the last one is refused invalid_request (400) — archive the product instead.
Change a tracked variant's on-hand count, with a reason
Changes a tracked variant's on-hand count, either by delta or to an absolute set_to, with a reason, and answers with the variant and the movement row it wrote.
The shop's stock log, newest first
The shop's stock log, newest first: every reservation, sale, restock and manual adjustment with the on-hand and reserved counts it left behind and the actor who caused it.
The shop's default markup and rounding
The shop's default markup and rounding rule, which is what variants priced cost_plus derive their price from.
Set the shop's default markup and rounding, repricing cost_plus variants
Sets the shop's default markup and rounding and immediately reprices every cost_plus variant; the response says how many were repriced and each change lands in the price history.
Every price change in the shop, newest first
Every price change in the shop, newest first, with the old and new amount, what caused it (a manual edit or a repricing) and who did it.
The shop's category tree, parents first
The shop's category tree, parents before their children.
Create a category
Creates a category, optionally under a parent.
Delete an unused category
Deletes a category and answers 204. Needs authority over the client — membership of its organization, an API key bound to this client, or tenant staff holding clients:manage; anything else is refus...
Rename or move a category
Renames a category or moves it under a different parent.
The shop's imports, newest first
The shop's bulk imports, newest first, each with its status and its create, update, error and applied counts.
Upload a CSV or XLSX (and optionally a ZIP of images) for preview
Nothing lands until the import is committed.
One import and its counts
One import with its current status and counts — poll this after starting or committing an import, both of which finish in the background.
The preview, row by row
The parsed preview, row by row: what each row would create or update, the image it resolved, and the validation errors that would stop it.
Apply a ready import in the background
Applies a previewed import in the background and answers 202 with the import moved to committing; poll the import to see it finish.
Drop an import that has not been committed
Drops an import that has not been committed, leaving the catalog untouched.
The merchant's API keys, without secrets
The merchant's API keys with their environment, scopes, status and last use.
Issue an API key that acts as this merchant
Only a signed-in member of the merchant's organization may issue a key; a key cannot mint more keys.
Revoke one of the merchant's keys
Revokes one of the merchant's keys and answers 204; the key stops authenticating at once.
The merchant's own webhook endpoints
A merchant endpoint receives the events that belong to this merchant: product.*, order.*, inventory.* and import.*.
Register a webhook endpoint for this merchant; the signing secret is returned once
Registers a webhook endpoint that receives only this merchant's events.
Stop deliveries to one of the merchant's endpoints
Stops deliveries to one of the merchant's endpoints and answers 204.
Delivery attempts to the merchant's endpoints
Delivery attempts to this merchant's endpoints, newest first, with response code and error.
Settlement and marketing balances
The client's settlement balance and its marketing balance.
Move the client's settlement money into its marketing account
Moves money from the client's settlement balance into its marketing account, where cashback rules draw from.
Set a merchant's per-transaction commission rate (tenant admin)
The tenant's negotiated marketplace commission for this one merchant, applied to every catalog sale it makes.
List this merchant's own cashback and loyalty rules
The merchant's own cashback and loyalty rules — the ones it owns, not the tenant-wide rules that may also apply to its sales.
Set a cashback or loyalty rule for this merchant, common or per-product
Sets one of the merchant's own reward rules, either common to the whole shop or bound to one offering by offering_id; a per-product rule overrides the common one for that product.
Turn off one of this merchant's own rules
Retires a rule the merchant owns, freeing its slot so a new rate can be set.
Orders
Multi-line orders against the catalog, and their fulfilment state.
The merchant's order book, newest first
The merchant's order book, newest first by created_at and optionally narrowed by status.
One of the merchant's orders
One of the merchant's orders with its lines, commission and payment.
Cancel an open order and release its stock
Cancels an open order from the merchant's side and releases the stock its lines reserved.
Put a paid order's units back on the shelf (after a refund), once
Puts a paid order's units back on the shelf after the money has been refunded — it moves stock, never money, and the refund is a separate call.
The calling shopper's orders, newest first
The calling shopper's own orders, newest first by created_at, ties broken by id so a page boundary never skips or repeats an order.
Reserve a cart from one merchant at catalog prices
Stock is reserved for each line (unless the variant does not track inventory or allows backorder) until the order is paid, canceled or expires.
One of the shopper's orders
One of the calling shopper's orders with its lines and payment.
Pay an open order with one instant payment
Idempotent by order: calling it again returns the same payment.
Cancel an open order and release its stock
Cancels the shopper's own open order and releases the stock it reserved.
Discovery
The public read surface over published clients and offerings, plus purchase and subscribe.
Browse and search the client directory
Browses the public client directory: only clients the platform has made active appear.
A client's public profile with its published offerings
A client's public profile with its published offerings.
A published offering with its client
One published offering with the client selling it.
Buy a one-off item; the catalog price is the only price
Buys one unit of a published item for the calling consumer.
Subscribe to a plan; amount and interval come from the catalog
Subscribes the calling consumer to a published plan.
Payouts
Moving a client's settlement money out of the loop. Books first, the transfer follows.
The client's payout statement, newest first
The client's payout statement, newest first, each row with the amount that left settlement, the fee the wallet kept, the rail and the ledger transaction behind it.
Pay out settlement money (books first, transfer follows)
Draws the merchant's settlement money to the tenant treasury and records the payout; the external transfer is executed off-platform, so this call moves the books, not the bank.
Webhooks
Endpoint registration, the emitted event log, and redelivery.
Delivery attempt log (admin)
Every delivery attempt with its attempt number, HTTP response code and error, newest first — the log to read when a receiver is not seeing events.
List webhook endpoints
The tenant's webhook endpoints with their filters and status.
Register a webhook endpoint; the signing secret is returned once
Registers a tenant-wide webhook endpoint.
List emitted events
Events this tenant has emitted, with the payload each delivery carried.
Re-enqueue an event to all matching endpoints
Re-enqueues one event to every endpoint whose filters match it, and answers with how many deliveries were enqueued.
Ledger and reporting
Tenant-wide transaction explorer, balance totals, movement metrics and the fee plan.
Tenant-wide transaction explorer with resolved legs (admin)
The tenant's transactions with every leg resolved to its owner, purpose, direction and commodity — the explorer behind the admin console.
Balance totals per owner type and purpose — the float equation view (admin)
Balances grouped by owner type, purpose and commodity, with the account count behind each row and the tenant's fee plan — the float view an operator reconciles against.
Money movement, revenue, exposure and reconciliation for a period (admin)
The reporting view behind the console dashboard.
Update the tenant fee plan (audited; admin)
Replaces the fee rule for each money path the body names and leaves every path it does not name untouched, so naming a path is what asks for it to change.
Tenant audit trail (admin)
The tenant's audit trail, newest first: who changed what, with the before and after of each mutation.
Operations and audit
The audit trail and the vendor-support access grants that gate WalletD's own staff.
List WalletD vendor-support approvals (partner admin only)
Expired and revoked grants remain in the response as operational and audit evidence.
Approve short-lived WalletD vendor-support access (partner admin only)
Approves one named WalletD support engineer to touch this tenant's production data for a bounded window, against a ticket reference and a stated reason.
Get the calling WalletD vendor-support identity's active grant
This is the only tenant endpoint a WalletD vendor-support identity may call without an active grant.
Revoke WalletD vendor-support access immediately (partner admin only)
Ends a support grant immediately; the engineer's next request is refused.
Platform administration
Tenant provisioning and per-tenant health. Platform staff only; not part of a partner integration.
List tenants (platform staff only)
Every tenant on this deployment, newest first, with its fee plan and commission mode.
Provision a tenant with its system accounts (platform staff only)
Provisions a partner loop: the tenant's ledger is created first, then the tenant row, so the tenant id is minted alongside its books.
Per-tenant health snapshot — balances, fee plan, ledger invariants (platform staff only)
The tenant's balance rollup by owner type, purpose and commodity, plus the one invariant a caller can check without holding the books: every commodity must net to zero across the whole ledger.
Whole-platform ledger view — every tenant's position and health (global admin only)
One row per tenant with its user count, 30-day movement, treasury float, outstanding liabilities and whether its books net to zero, plus totals per currency.
Ecosystem clients across all tenants, the review queue (global admin only)
Ecosystem clients across every tenant — the moderation queue.
Let a pending client publish to Explore (platform staff only)
Lets a pending client publish its offerings to Explore.
Hide a client's whole catalog from Explore (platform staff only)
Suspension is moderation, not confiscation: the catalog disappears from Explore while settled money stays settled and a payout still works.
Cross-tenant transaction explorer (global admin only)
Every tenant's transactions with their resolved legs, optionally narrowed by tenant and by type.
Wallet users across all tenants (global admin only)
Wallet users across every tenant, optionally narrowed by tenant and by a free-text query.
Subscriptions across all tenants (global admin only)
Subscriptions across every tenant, optionally narrowed by tenant and by status.
System
Liveness. Unauthenticated, and the only path outside the bearer scheme.