All specs
infrastructurehigh complexity

Payments & Billing

Used in 5 specs

Charge customers via one-time purchases, subscriptions, or usage-based billing.

Options

Billing Model*

Single charge per product or service
Monthly or annual recurring billing
Charge based on consumption (API calls, seats, etc.)

Payment Processor*

Full-featured; best-in-class developer experience
Merchant of record; handles VAT/tax automatically

Decision Points

Is the revenue model recurring (SaaS)?

If yes

Choose subscription billing. Evaluate usage-based if pricing scales with consumption.

If no

One-time purchase is far simpler. Consider Stripe Checkout for a no-code option.

Is global VAT/sales tax compliance a concern?

If yes

Use Paddle as merchant of record — they handle tax across jurisdictions.

If no

Stripe gives more control; integrate TaxJar or Stripe Tax if needed later.

Do you want to offer a free trial without requiring a card upfront?

If yes

Use reverse trials — free-tier access with a prompt to add a card at the end. Higher signup conversion but lower trial-to-paid conversion.

If no

Card-required trials filter out tire-kickers and produce 2–3x higher trial-to-paid rates. Stripe supports both via checkout.

Do you sell to enterprise customers with procurement processes (POs, net-30 terms)?

If yes

Support invoicing workflows (Stripe Invoicing or manual PDF invoices via finance). Self-serve credit-card checkout is insufficient at that ACV.

If no

Credit-card-only is simpler and covers all SMB/prosumer use cases.

Do you sell in markets where customers transact in non-USD currencies?

If yes

Enable multi-currency pricing in Stripe or Paddle. Price in local currency — EU/UK customers strongly prefer EUR/GBP over USD conversions.

If no

USD-only is simpler; add currencies only when a market demands it.

Will you close large B2B deals that need ACH or wire transfer (>$5k)?

If yes

Enable Stripe ACH Credit Transfer or wire instructions on invoices. Credit-card fees on large invoices are prohibitive.

If no

Card-only is fine for SMB and prosumer ticket sizes.

Do you have EU customers (SCA/3DS compliance required)?

If yes

Use Stripe Payment Intents (handles 3DS authentication automatically) or Paddle. Do not use raw Charges API — it predates SCA.

If no

Still use modern Payment Intents API — SCA will apply to US processors eventually.

Is self-serve cancellation acceptable, or do you need "contact us to cancel"?

If yes

Self-serve cancellation via Stripe Customer Portal — legally required in California (FTC Click-to-Cancel) for many subscriptions.

If no

Contact-us friction increases short-term retention but damages NPS and is increasingly regulated. Think twice.

Do marketing or sales teams need to issue coupons and discounts?

If yes

Use Stripe Coupons / Paddle Discounts. Support percentage and fixed-amount discounts with expiry and redemption limits.

If no

Skip — discount UX adds complexity and is rarely needed outside marketing-led motions.

Do users frequently upgrade/downgrade mid-cycle?

If yes

Enable proration in Stripe (proration_behavior: create_prorations). Immediate upgrade + end-of-period downgrade is the customer-friendly pattern.

If no

Wait-until-renewal plan changes are simpler; skip proration logic.

Do you have >1000 paying customers or expect significant failed-payment volume?

If yes

Enable Stripe Smart Retries (free) plus a custom dunning email sequence (day 0, 3, 7, 14). Recovers 30–50% of failed payments.

If no

Default Stripe retries are enough; add custom dunning once failed payments become a meaningful revenue leak.

Should customers manage their own billing (payment methods, invoices, plan changes)?

If yes

Use Stripe Customer Portal or Paddle Retain — pre-built UI, handles tax/invoices/cancellation. Massive support-ticket reducer.

If no

Build a minimal billing page and route the rest to support — only viable at low customer counts.

Do you connect buyers and sellers and need to split payments (marketplace)?

If yes

Use Stripe Connect (Standard or Express accounts). Do not build split payments yourself — tax forms, KYC, and payouts are legal minefields.

If no

Standard direct charges are simpler and correct for first-party sales.

Do you need to issue refunds regularly with reason tracking and approval flows?

If yes

Build an internal refund tool that captures reason, links to audit log, and uses Stripe Refunds API. Required for support scale and compliance.

If no

Manual refunds through the Stripe dashboard are fine until volume demands tooling.

Are you tempted to store raw card numbers to avoid re-entry (PCI Level 1 scope)?

If yes

Do not. Use Stripe Payment Methods or Paddle saved cards — tokenized references keep you out of PCI DSS Level 1 scope. The compliance overhead is massive.

If no

Good — always tokenize. Stripe Elements, Paddle Checkout, or hosted checkout keeps card data off your servers entirely.

Tradeoffs

ComplexitySubscription billing selected

Requires handling trial periods, dunning, proration, and cancellation flows

ComplexityUsage-based billing selected

Must instrument every billable action and send metered events to billing provider

UXPaddle selected

Less customizable checkout; Paddle acts as legal seller so you avoid VAT registration

Go Deeper

Dependencies

user-system

Implementation Examples

Stripe

The developer-first payment platform — subscriptions, invoicing, and 135+ currencies.

Paddle

Merchant of record that handles global tax compliance and subscription management.

Lemon Squeezy

All-in-one platform for selling digital products with built-in tax handling.

Used by specs

E-commerce StorefrontSaaS StarterMarketplace PlatformDeveloper Tool / API ProductAI-Powered SaaS