vela-checkout

Hosted checkout application at pay.velapay.com. Public-facing billing surface for payment links, invoices, and direct checkout URLs.

Purpose and Role

• Public checkout at pay.velapay.com where subscribers complete billing authorization.
• Payment links with unique URLs per checkout session (shareable via email, social media, QR code).
• Invoice pages with line items, tax calculation, and PDF generation.
• Email delivery of invoices via Resend integration.
• Turnstile bot protection on public checkout pages.
• Shared checkout-session creation pattern with vela-portal (for plan switching).
• Wallet approval flow — subscribers connect wallet, review terms, sign mandate creation.

Tech Stack

Technology	Version	Purpose
React	19.x	UI library
Hono	4.12.x	API layer (Cloudflare Worker)
Cloudflare D1	GA	Session storage, checkout state
Cloudflare Workers	—	Compute runtime
@vela/sdk	latest	Checkout transaction building
Cloudflare Turnstile	—	Bot protection
Tailwind CSS	4.2.x	Styling
wrangler	4.78.x	Cloudflare CLI
Resend	—	Email delivery for invoices

Directory Structure

vela-checkout/
├── src/
│   ├── app/                   # React SPA
│   │   ├── components/
│   │   │   ├── checkout/
│   │   │   │   ├── CheckoutShell.tsx    # Main checkout layout
│   │   │   │   ├── WalletConnect.tsx    # Direct wallet connection
│   │   │   │   ├── PlanReview.tsx       # Plan terms display
│   │   │   │   └── Confirmation.tsx     # Transaction confirmation
│   │   │   └── invoice/
│   │   │       ├── InvoicePage.tsx      # Invoice display
│   │   │       └── InvoicePDF.tsx       # PDF generation
│   │   ├── hooks/
│   │   │   ├── useCheckoutFlow.ts       # Checkout session management
│   │   │   └── useWalletDetect.ts       # Wallet detection
│   │   └── pages/
│   │       ├── checkout.tsx             # /checkout/:sessionId
│   │       ├── invoice.tsx              # /invoice/:invoiceId
│   │       └── link.tsx                 # /link/:linkId
│   ├── worker/                # Hono Worker (backend API)
│   │   ├── index.ts           # Worker entry
│   │   ├── routes/
│   │   │   ├── checkout.ts    # Checkout session CRUD
│   │   │   ├── invoice.ts     # Invoice generation
│   │   │   └── payment-link.ts # Payment link management
│   │   └── middleware/
│   │       └── turnstile.ts   # Turnstile verification
│   └── lib/
├── wrangler.toml              # D1 binding, Turnstile secret
├── vite.config.ts
└── package.json

Deployment Target

• Cloudflare Workers: Hono Worker for API + React SPA for UI.
• Domain: pay.velapay.com.

Dependencies

What It Depends On

Dependency	Type	Purpose
@vela/sdk	npm package	Checkout transaction building, PDAFactory
vela-dashboard	API proxy	Checkout session creation (shared D1)
Cloudflare D1	Infrastructure	Session and checkout state storage
Cloudflare Turnstile	Infrastructure	Bot protection
Resend	Infrastructure	Invoice email delivery

What Depends on It

Nothing. Checkout is a terminal consumer — subscribers use it directly.

Current Status

• v1.5 complete: Hosted checkout with payment links and invoice pages.
• v1.8 complete: Playwright E2E validation, Resend email delivery, multi-token rendering.

Notable Design Decisions

Separate from Dashboard

Checkout is a public-facing app with no merchant auth. Extracting it from the dashboard keeps:

• Public traffic isolated from merchant endpoints.
• Deploy cadence independent from merchant features.
• Attack surface minimized (no merchant auth, no org management).

Shared Checkout-Session Pattern

Both vela-checkout and vela-portal (for plan switching) use the same checkout-session creation pattern. Sessions are stored in D1 and consumed by whichever surface initiates the flow.

Direct Wallet Connection (No iframe)

Unlike the widget, hosted checkout connects the wallet directly on the page. No iframe boundary, no postMessage relay. This simplifies the checkout flow and enables features like QR code wallet pairing.

Turnstile Bot Protection

Public checkout pages are gated with Cloudflare Turnstile to prevent automated abuse (mass subscription attempts, scraping checkout sessions, brute-forcing session IDs).

Payment Links with QR Codes

Each checkout session has a unique URL (pay.velapay.com/checkout/cs_abc123). Merchants share this URL via email, social media, or QR code. UTM parameters are tracked for analytics.

Invoice Generation

Extended checkout flow supports invoices with line items, tax calculation, PDF generation, and email delivery via Resend. Invoice pages are separate from checkout pages but use the same session management.