Payments
Sell subscriptions, digital products, and usage tiers with unified billing and webhooks.
VibeKit provides a complete billing architecture so you can monetize your product without getting locked into a single processor. With one central catalog and an automated webhook reconciliation engine, your product grants access only when real payment evidence clears.
Selling Subscriptions and One-Time Products
Every paid tier in your application connects to a single unified catalog in packages/payments/catalog.ts. You define your products, billing intervals (monthly, yearly, or lifetime), seat allowances, and feature entitlements once:
- Subscription Plans: Monthly and annual recurring billing with automated grace periods, prorated upgrades, and cancellation schedules.
- One-Time Purchases: Lifetime software licenses, pay-as-you-go credit bundles, or digital product downloads.
- Entitlement Tracking: Check user and team access directly in server procedures with
hasActiveSubscriptionandgetEffectiveEntitlementwithout querying third-party APIs on every page load.
Multiple Payment Gateways Without Code Changes
You never need to rewrite your checkout flow when switching processors. VibeKit abstracts vendor differences behind a standard adapter interface:
| Provider | Ideal Use Case | Webhook Verification |
|---|---|---|
| Stripe | Global cards, Apple Pay, Google Pay, and localized bank rails. | Native signed webhook signature checks. |
| Lemon Squeezy | Merchant of Record for global digital goods and EU VAT handling. | HMAC SHA-256 payload verification. |
| Paddle | Merchant of Record for B2B software and international tax compliance. | Signed signature headers with public key verification. |
| Polar | Developer-centric monetization, sponsorship tiers, and GitHub integration. | Secret header validation. |
| Dodo Payments | Global cross-border payments with high local conversion. | Webhook signing secret verification. |
| Mock Provider | Offline local testing and automated CI test runs without API keys. | Immediate local fulfillment simulation. |
Set PAYMENTS_PROVIDER in your .env file to the provider of your choice. In local development, MOCK_SERVICES=true enables the mock provider, allowing you to test checkout modals and upgrade flows instantly.
Bulletproof Webhook Reconciliation
Browser redirects after checkout can be forged, delayed, or closed before redirecting back to your application. VibeKit treats browser return URLs as purely cosmetic and grants access only through verified server webhooks:
- Durable Checkout Intent: Before opening the checkout window, VibeKit creates a checkout intent in your PostgreSQL database to record local business uniqueness.
- Signed Webhook Inbox: When payment succeeds, the provider sends an event to
/api/webhooks/payments. VibeKit verifies the cryptographic signature before reading the payload. - Idempotent Processing: Webhook events are logged in the database to prevent replay attacks or duplicate credit grants if a provider retries delivery.
- Historical Connection Stability: If you switch from Stripe to Lemon Squeezy later, past subscription records remain tied to their original provider connection so recurring renewals and cancellations continue to resolve cleanly.
Self-Serve Customer Billing Portal
Users and team owners can manage their subscriptions without contacting support:
- Update Payment Methods: Customers can change credit cards or billing addresses securely through provider-hosted customer portals.
- Plan Upgrades and Downgrades: Upgrade immediately with prorated billing or schedule a downgrade for the end of the current billing period.
- Download Invoices: Access past receipts and tax invoices directly from account settings.
Guiding Your Agent to Build Paywalls
Your coding agent can gate features, create pricing cards, or adjust plans using existing VibeKit payment utilities. Give your agent targeted instructions:
Add a Pro subscription tier to our pricing table for $29/month.
Update 'packages/payments/catalog.ts' with the plan details and feature entitlements.
Gate the '/dashboard/export' route so only teams with an active Pro subscription can export CSV files.
Use the mock payment provider so we can verify the checkout flow locally in development.