Error subclass for user-facing payment validation errors (e.g. invalid phone number). These propagate through safeAsync so the message can be shown to the user.

Build a checkout's signed metadata the way the given provider needs it, with the caps read from the provider registry: build the logical shape within the per-value and entry caps, pack the small fields into one entry when the provider needs that to fit, and enforce the caps on the shape that reaches the wire. SumUp's caps are unbounded (its metadata is stored locally, never sent to the provider), which makes the enforcement a no-op for it.

Build checkout session metadata from booking data (items already compact).

Render a priced order into a provider's line-item array: each ticket line via line, each extra (booking fee, …) via extra. Providers supply the two shape callbacks; the ordering (tickets, then extras) matches what Stripe and Square built by hand before.

Cache a provider API client keyed on its config. Reuses the cached client while the config is unchanged and recreates it when the config changes; returns null when the provider is unconfigured.

Build a standalone-line CheckoutItem for one listing — the shared shape every single-listing checkout (direct-to-provider QR booking, the plain public booking form) builds its one-item items array from.

Create a withClient helper that runs an operation with a lazily-resolved client. Returns null if the client is not available or the operation fails.

Enforce a payment provider's metadata limits.

Normalize validated session metadata into the canonical SessionMetadata shape.

True when the listing still has spots for this quantity on this date (no date for a date-less listing, whose capacity is one running total).

Build a provider's createCheckoutSession: call the provider's own create function, read the session id and URL off whatever shape it returns, and map that to a shared CheckoutSessionResult — all inside the standard checkout error guard. Each provider only supplies its create call, how to read the id/url, and its display label.

Collapse the packable small fields into one JSON b entry, dropping them from the top level. Falsy values are omitted (the "" = absent convention), so the b entry only appears when at least one packed field is actually present.

Process a single-listing booking.

Build a test webhook delivery: JSON-encode the event, sign it with the provider's own signing rule, and return the payload/signature pair a test can POST to the webhook route. Each provider supplies only sign.

Convert single-listing answerIds to the per-listing format used in metadata

Convert registration line items to compact, edge-tagged booking items (v2). Each package member line carries ITS OWN package edge (k:"p", r=its group id) so the webhook can revalidate each line's nodeKey — an order can book several packages, so the edge is per line, never order-wide; folded children (in allocations) and standalone lines stay untagged. See signed-metadata.ts.

Normalise a provider timestamp to the ledger's canonical ISO 8601 form (YYYY-MM-DDTHH:mm:ss.sssZ), or undefined when it's absent or unparseable.

Convert a provider-specific checkout result to a CheckoutSessionResult. Returns null if session ID or URL is missing.

Compact the resolved modifier specs to id/quantity references for metadata.

Assemble the one ValidatedPaymentSession shape every provider adapter returns. Owns the createdAt rule — the key is left out entirely when the provider gave no usable timestamp — and normalizes the guarded wire metadata into the canonical shape. metadata must already have passed hasRequiredSessionMetadata (or come from our own staged checkout row).

Wrap a checkout operation, converting PaymentUserError to { error } result and swallowing unexpected errors as null. Used by both provider adapters.

Payment provider interface.

Processed booking intent extracted from payment session metadata

Booking result — callers map this to their response format

Registration intent for checkout (one or more listings)

Single item within a checkout — one bookable PATH. A listing booked through two overlapping packages (or a package plus its own standalone row) in one order is one item per path, each with its own quantity and price.

Result of creating a checkout session.

Run an operation with the lazily-resolved client. Returns null when the client is unconfigured or the operation fails (unless the error should propagate). The named type keeps the contract visible to callers of the widely-used stripeClientRuntime.run so a signature drift fails at the definition instead of leaking to callers.

Shared shape for a provider credential check in connection-test results.

Per-listing answer references carried through a checkout, shared by the booking and checkout intents.

Compact modifier reference stored in session metadata: the modifier id and the quantity taken. The webhook re-fetches the modifier by id and re-derives its amount from the current database — provider metadata amounts are never trusted.

A modifier resolved for a specific checkout — the input the pricing pipeline applies. Eligibility (scope, stock, codes) is decided upstream; by the time a spec reaches pricing it is known to apply. value is the signed calc value (see modifierDelta); listingIds scopes which items it is charged on (null = the whole order); quantity is how many the buyer took (1 for an automatic or code modifier, more for an opt-in add-on).

Supported payment provider identifiers

Valid payment status value

Metadata attached to a validated payment session.

Set up a webhook endpoint for a provider. Some providers (e.g. Stripe) support programmatic creation; recreating any existing endpoint returns a fresh signing secret. Shared by the provider interface and each provider's own implementation so the signature can't drift.

The payload/signature pair a test POSTs to a provider webhook route.

A validated payment session returned after checkout completion

Provider-agnostic webhook event

Result of webhook endpoint setup

Result of webhook signature verification

Stubbable API for internal calls (testable via spyOn, like stripeApi/squareApi)

Schema for valid payment status values. "failed" is a terminal non-payment (declined or expired checkout) — distinct from "unpaid", which may still complete.

Safely execute async operation, returning null on error. Re-throws PaymentUserError so user-facing messages propagate.