Payment processing with Stripe and Square.
A provider-agnostic payment interface with adapters for Stripe and Square. Handles checkout sessions, webhook verification, refunds, and idempotent payment processing.
Provider Interface
PaymentProvider defines the common contract:
- Create single and multi-event checkout sessions
- Verify webhook signatures
- Retrieve session details and process refunds
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 intent metadata for a multi-event checkout. Common fields: multi flag, name, email, serialized items, optional phone/date.
Build intent metadata for a single-event checkout. Common fields: event_id, name, email, quantity, optional phone/address/date.
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.
Extract a human-readable message from an unknown caught value
Normalize validated session metadata into the canonical SessionMetadata shape.
Resolve the active payment provider based on admin settings. Lazy-loads the provider module to avoid importing unused SDKs. Returns null if no provider is configured.
Validate that session metadata contains required fields (name) and either event_id (single) or multi+items (multi). Returns false if validation fails.
Type guard: check if a string is a valid PaymentStatus
Process a single-event booking.
Safely execute async operation, returning null on error. Re-throws PaymentUserError so user-facing messages propagate.
Serialize multi-ticket items for metadata storage (compact JSON)
Convert a provider-specific checkout result to a CheckoutSessionResult. Returns null if session ID or URL is missing.
Booking result — callers map this to their response format
Result of creating a checkout session.
Registration intent for multi-event checkout
Supported payment provider identifiers
Valid payment status values
Registration intent for a single event checkout
A validated payment session returned after checkout completion
Result of webhook endpoint setup
Result of webhook signature verification
Stubbable API for internal calls (testable via spyOn, like stripeApi/squareApi)
Usage
import * as mod from "docs/payments.ts";