Money: obligations, captures, refunds

The obligation

When a booking is sold, an obligation is opened for it: what the customer owes for this booking, addressed by obligation_ref (a UUID the storefront mints at purchase). Every charge, deposit, balance payment, refund and price revision is posted against that one reference, so a booking’s money story is always one query away. The guest’s confirmation number QS-XXXXXXXX is the hex prefix of the same reference.

GET /obligations/{obligation_ref}/balance returns the live position: owed, settled, and the balance.

Captures

A capture is a charge over the tenant’s processor rail (Stripe or Finix today; the rail is pluggable and the API does not change with the processor). There are two ways in:

• Customer-present — POST /storefront/purchases, with a tokenised instrument from the processor’s client library. Settles a booking intent. This is what the storefront uses.
• Operator — POST /captures/via-rail, from a session. capture: "now" charges a customer-present token; capture: "on_file" charges off-session against a stored instrument (credential_id), which is how a balance or an upcharge is collected from a card the guest left on file.

Both run the same engine: commit seats → price (net + tax from the governed catalog) → charge → record. The response reports processor_ref and the net_minor / tax_minor / gross_minor split.

settlement: "deposit" on a purchase charges the policy-derived deposit and leaves the remainder owed; the balance is then collected by a balance link or an on-file capture before the activity.

Balances and balance links

A balance is collected from the guest with a balance link (POST /obligations/{ref}/balance-links): a single-use /b/{token} page that charges exactly the obligation’s live balance, read when the page renders and again when the guest pays, so a link never carries a stale amount. Links expire (default and maximum 14 days), can be cancelled, and minting a new one supersedes the old. POST /obligations/{ref}/charge-balance collects the balance off-session from a stored instrument instead.

GET /money/receivables lists open balances across the tenant; GET /money/refunds lists executed refunds; GET /money/summary is the operator’s money view — receivables by departure date, executed refunds and decisions waiting. These are core’s own records (source: "core"), not the ledger’s and not the processor’s: revenue and the nightly tie are ledger facts and live under /ledger/*.

Refunds

Refunds are never issued directly. A cancellation (full or by policy fraction), a downgrade rebook, an add-on removal or a departure cancellation requests a refund as part of its own transaction, and the ledger settles it asynchronously against the original capture — through the same processor, to the same instrument. There is no endpoint that takes an arbitrary refund amount; the amount is always derived from facts (what was captured, what the policy says).

This matters for integrators: after a cancellation returns 202, read the obligation’s balance or /money/refunds to see the refund land rather than expecting it in the cancellation response.

Revenue recognition

Quikstik keeps accrual accounts. A sale is a liability (customer deposit / deferred revenue) until the activity date; revenue is earned in full on the day of the activity, never before. An unpaid balance is a real receivable. The ledger ties to the processor’s balance nightly.

The ledger

Everything above lands in a double-entry journal written by exactly one component and never by hand. It is read-only over HTTP:

Endpoint	Returns
GET /ledger/trial-balance	Every account’s debit/credit position as of a date
GET /ledger/receivables	Open receivables per obligation
GET /ledger/channel-receivables	What each sales channel (OTA) owes
GET /ledger/pl	Profit and loss for a period
GET /ledger/entries	Paged journal entries with their lines
GET /ledger/obligations/{obligation_ref}	The full journal of one booking’s money
GET /ledger/health	Whether the ledger ties

Amounts are integer minor units. The ledger is the source an accountant reconciles against; the operational reads under /money/* are projections of it.