Appearance
v1.5 Hosted Checkout & Billing
Shipped: 2026-04-09 | Phases: 7 (29–35) | Plans: 37 | Audit: 86/86 requirements, tech_debt accepted
The milestone with the most plans (37). v1.5 brought Stripe-grade billing UX to Solana: hosted checkout pages, automatic invoicing, failed payment handling, a customer self-service portal, embeddable pricing tables, and conversion analytics.
What Shipped
Phase 29: Checkout Sessions + Hosted Page + Payment Links
The new vela-checkout repo and payment link infrastructure.
- Hosted checkout — Standalone branded checkout pages at checkout.velapay.com
- Session API — Create checkout sessions with plan, merchant, and subscriber configuration
- SDK support —
@vela/sdkcheckout session creation and management - Payment links — Persistent links that create fresh checkout sessions on each visit
- QR code downloads for mobile scanning
- UTM parameter passthrough for marketing analytics
- Qualified-view tracking for conversion measurement
- Wallet approval flow — SIWS-based wallet connection during checkout
- Turnstile gating — Bot protection on public checkout pages
Phase 30: Invoicing + Failed Payments + Webhook Reliability
The billing operations layer.
- Invoice pipeline — Automatic invoice generation for every completed payment
- PDF generation + R2 delivery — Invoices stored in Cloudflare R2, downloadable by merchants and subscribers
- Hosted invoice pages — Public invoice viewing at invoice.velapay.com
- Resend email plumbing — Email delivery for invoice notifications (live delivery pending staging)
- Grace period retry handling — Failed payments retry within a configurable window
- Reconciliation — Cross-check between on-chain state and D1 billing records
- DLQ support — Dead letter queue for permanently failed billing events
Phase 31: Customer Portal + Pricing Table + Analytics
The new vela-portal repo and embeddable components.
- Subscriber portal — Self-service portal for subscribers at portal.velapay.com
- SIWS and magic-link authentication
- Multi-wallet identity support
- Invoice downloads
- Subscription cancellation
- Self-serve plan switching
<vela-pricing-table>— Embeddable Shadow DOM component- Declarative Shadow DOM (DSD) support for SSR
- Customizable theming
- WCAG-conscious interaction design
- Real hosted-checkout launch behavior
- Checkout funnel analytics — Conversion tracking from checkout page → wallet connect → payment completion
- Arcium-sealed response support for private analytics
- Schema extensions — D1 tables for checkout sessions, invoices, and analytics events
Phases 32–35: Integration + Blocker Closure + Traceability
Four phases dedicated to closing gaps and achieving full requirement coverage.
- Phase 32: Integration fixes + unclaimed requirements — Service-binding, auth, schema-sync fixes for checkout and pricing flows
- Phase 33: Verification + traceability cleanup — Verification reports, traceability cleanup, dead-code removal
- Phase 34: Milestone blocker closure — Fixed 4 previously-blocking requirements:
CSESS-06— Checkout completion queue payload was being droppedPTBL-08— Pricing-table subscribe launched the wrong route shapePORT-02— Magic-link auth path was unreachablePORT-11— Portal switch-plan flow was intentionally disabled
- Phase 35: Traceability + validation closure — Summary backfills, Nyquist closure, re-audit preparation
Key Architectural Decisions
Why vela-checkout Is Separate from vela-widget
- vela-widget — Embeddable checkout overlay (iframe-based, loaded into merchant sites). 2.6KB, minimal footprint.
- vela-checkout — Standalone hosted checkout page (full page at checkout.velapay.com). Owns its own session API, auth flow, and payment processing.
Different deployment targets, different UX patterns, different security boundaries. Combining them would create unnecessary coupling.
Shared Checkout-Session Creation
Both the pricing table and the subscriber portal create checkout sessions through the same internal route. This means:
- Single source of truth — All session creation goes through one code path
- Consistent behavior — Pricing table and portal launches are functionally identical
- Simplified testing — Test the session API once, cover both surfaces
Public Billing Apps Proxy to Dashboard Internal Routes
vela-checkout and vela-portal are public-facing Cloudflare Workers. They proxy sensitive operations to the dashboard Worker via service bindings:
Checkout Worker ──service binding──→ Dashboard Worker (internal /checkout-internal/*)
Portal Worker ──service binding──→ Dashboard Worker (internal /portal-internal/*)This keeps auth and billing logic centralized while allowing public checkout and portal surfaces.
Audit Results
Scorecard
| Area | Score | Notes |
|---|---|---|
| Requirements satisfied | 86/86 | Every requirement checked and verified |
| Phases verified | 7/7 | Phases 29–35 all have verification artifacts |
| Integration | 6/6 | All cross-phase handoffs wired |
| E2E flows | 7/7 | All targeted flows pass at code/test level |
Previously Blocking Requirements (Fixed in Phase 34)
| Requirement | Problem | Fix |
|---|---|---|
| CSESS-06 | Queue payload dropped before downstream processing | Safe payload emission + queue consumer acceptance |
| PTBL-08 | Pricing-table launched wrong route shape | POST to real session-creation path with checkout proxy |
| PORT-02 | Magic-link auth unreachable | Route mounting + request/consume endpoints |
| PORT-11 | Switch-plan intentionally disabled | SwitchPlanModal with preview + reauth |
Accepted Tech Debt
The v1.5 audit accepted the following tech debt, tracked for Phase 47 (v1.8):
- Real Resend delivery — Email plumbing is wired but live delivery needs staging confirmation
- Hosted invoice visual QA — PDF invoices need visual acceptance testing in staging
- Queue/DLQ timing measurement — Deployed queue behavior needs real-world timing validation
- Live wallet acceptance — Real installed-wallet spot-check recommended
- Pricing table accessibility — Full accessibility sweep needed in staging
This debt was explicitly accepted because it requires staging infrastructure that didn't exist at v1.5 time. Phase 47 (v1.8) includes staging E2E acceptance that will close these items.
What Worked
- Phase 34 blocker closure — Fixing 4 blocking requirements in a dedicated phase was more effective than trying to close them in-band
- Shared session creation — Single code path for pricing table and portal checkout
- Shadow DOM pricing table — DSD support means the pricing table renders even without JavaScript
- Service binding isolation — Public checkout and portal Workers never touch D1 directly
What Was Inefficient
- 7 phases for one milestone — The scope was too broad. Later milestones (v1.7, v1.8) adopted more aggressive phase merging.
- 4 closure phases (32–35) — Nearly half the milestone was integration and cleanup. Better upfront integration testing would have reduced this.
- Traceability backfill — Phase 33/35 were dedicated to backfilling verification artifacts that should have been written during execution.
Key Lessons
- Close blockers in dedicated phases — Phase 34's focused blocker closure was highly effective. Better than squeezing fixes into feature phases.
- Accept tech debt explicitly — The staging validation debt was documented and tracked, not ignored. This prevented scope creep while keeping the debt visible.
- Shared internal routes reduce duplication — Having checkout and portal share session creation via internal routes prevented behavioral drift between surfaces.
- Plan for staging early — Several acceptance items couldn't be closed without staging infrastructure. Staging should be available before the billing milestone, not after.