Checkout Methods

Available Checkout Methods

🎯 Embedded Form

🔗 External Redirect⚛️ React Stripe🔗 Payment Link

NEXT_PUBLIC_STRIPE_CHECKOUT_TYPE="EmbededForm"

Best for: Optimal user experience with no redirectsComponent location: src/components/features/checkout-stripe/embed/Features:

• Stripe Elements integration
• Real-time validation
• Custom styling
• Mobile-optimized
• No page redirects

NEXT_PUBLIC_STRIPE_CHECKOUT_TYPE="ExternalForm"

Best for: Quick setup with Stripe-hosted securityComponent location: src/components/features/checkout-stripe/external-checkout/Features:

• Stripe-hosted checkout
• PCI compliance by default
• Multiple payment methods
• Built-in security features
• Minimal code required

NEXT_PUBLIC_STRIPE_CHECKOUT_TYPE="ReactStripeForm"

Best for: Advanced customization with React componentsComponent location: src/components/features/checkout-stripe/react-stripe/Features:

• Custom React components
• Advanced form controls
• Custom validation logic
• Complex integration scenarios
• Full UI control

NEXT_PUBLIC_STRIPE_CHECKOUT_TYPE="PaymentLink"

Best for: Simple payments and easy sharingComponent location: src/components/features/checkout-stripe/payment-link/Features:

• No-code solution
• Share via email/social
• Stripe-hosted pages
• Quick implementation
• Mobile-friendly

Unified Checkout Page

// From src/components/features/checkout-stripe/checkout-page.tsx
export default async function CheckoutPage({
  priceId,
  couponId,
  seats = 1,
  guest = false,
  enableInstallments = false,
}: {
  priceId: string
  couponId: string
  seats: number
  guest: boolean
  enableInstallments?: boolean
})

Checkout Configuration

// From src/components/features/checkout-stripe/checkout-page.tsx
const checkoutConfig = getCheckoutConfig({
  enableInstallments,
  recapInfo,
  priceId,
  seats,
  guest,
  isRecurring,
})

Method Details

🎯 Embedded Form (Recommended)

// From checkout-page.tsx
<CheckoutFormEmbedded
  priceId={priceId}
  seats={seats}
  couponId={couponId}
  guest={guest}
/>

• Best UX: No page redirects, faster checkout
• Custom Styling: Match your brand design
• Real-time Validation: Instant feedback on form fields
• Mobile Optimized: Responsive design for all devices
• Secure: Stripe Elements handle sensitive data

• You want the best user experience
• You need custom styling
• Mobile optimization is important
• You prefer embedded solutions

🔗 External Redirect

// From checkout-page.tsx
<CheckoutButtonExternal
  priceId={priceId}
  seats={seats}
  couponId={couponId}
  guest={guest}
/>

• Quick Setup: Minimal integration required
• Stripe Security: PCI compliance handled by Stripe
• Payment Methods: All Stripe payment methods available
• Localization: Automatic language detection
• Mobile Apps: Works well with mobile redirects

• You want minimal development time
• PCI compliance is a concern
• You need all payment methods
• Mobile app integration

⚛️ React Stripe Integration

// From checkout-page.tsx
<CheckoutButtonReactStripe
  priceId={priceId}
  seats={seats}
  couponId={couponId}
  guest={guest}
/>

• Custom Components: Build your own checkout UI
• Advanced Logic: Complex validation and flows
• Integration Control: Full control over the process
• React Ecosystem: Use React libraries and patterns
• Custom Validation: Implement business-specific rules

• You need complex custom checkout flows
• Advanced validation requirements
• Integration with React ecosystem
• Custom business logic requirements

🔗 Payment Links

// From checkout-page.tsx
<CheckoutPaymentLink
  priceId={priceId}
  seats={seats}
  couponId={couponId}
/>

• No Code: Create payment links in Stripe dashboard
• Easy Sharing: Share via email, social media, or messaging
• Quick Setup: Fastest implementation method
• Mobile Friendly: Optimized for mobile sharing
• Stripe Hosted: Fully managed by Stripe

• You need to share payment links
• Minimal development resources
• Social media or email campaigns
• Quick payment collection

Advanced Features (Custom System Only)

Guest Checkout

// Enable guest checkout
<CheckoutPage
  priceId="price_123"
  couponId=""
  seats={1}
  guest={true} // Allow checkout without account creation
/>

1. Guest Payment: User completes payment without creating account
2. Webhook Processing: handleGuestCheckoutSessionCompleted function processes the event
3. User Creation: System automatically creates user account from checkout data
4. Subscription Linking: Links the new user to their paid subscription
5. Account Access: User can access their account and manage subscription

// From src/lib/stripe/stripe-events.ts
function detectGuestCheckoutMode(metadata: Record<string, string>): boolean {
  const referenceId = metadata.referenceId
  const guestCheckoutFlag = metadata.guest_checkout === 'true'

  const isGuestByReferenceId = referenceId === 'guest'
  const isGuestByFlag = guestCheckoutFlag
  const isGuestCheckout = isGuestByReferenceId || isGuestByFlag

  return isGuestCheckout
}

// From src/lib/stripe/stripe-events.ts
async function createGuestUser(customerData: {
  customerEmail: string
  customerName?: string
  stripeCustomerId?: string
}) {
  // 1. Ensure Stripe customer exists
  const finalStripeCustomerId = await ensureStripeCustomer(customerData)

  // 2. Create or update database user
  const finalUser = await ensureDatabaseUser(
    customerData.customerEmail,
    customerData.customerName,
    finalStripeCustomerId
  )

  return finalUser
}

// From src/lib/stripe/stripe-events.ts
async function updateSubscriptionWithUser(
  subscriptionId: string,
  user: { id: string; email: string; stripeCustomerId: string }
) {
  // Use billing context to determine correct referenceId
  const { referenceId } = await getBillingContext(user.id)

  const updatedSubscription = await updateSubscriptionForWebhookService({
    subscriptionId,
    referenceId,
    stripeCustomerId: user.stripeCustomerId,
  })
}

• Zero Friction: No account creation required during checkout
• Higher Conversion: Reduces checkout abandonment
• Automatic Account: User gets account access post-purchase
• Seamless Experience: User can manage subscription immediately
• Data Integrity: Proper linking between user, customer, and subscription

Payment Installments (Custom System)

// Enable installments
<CheckoutPage
  priceId="price_123"
  couponId=""
  seats={1}
  guest={false}
  enableInstallments={true} // Enable installment payments
/>

• Klarna, Affirm, and other BNPL options
• Automatic eligibility checking
• Increased purchasing power
• Higher conversion rates

Multi-seat Subscriptions (Custom System)

// Multi-seat subscription
<CheckoutPage
  priceId="price_123"
  couponId=""
  seats={5} // Number of seats/users
  guest={false}
/>

• Per-seat pricing calculation
• Volume discounts
• Prorated billing
• Seat management post-purchase

Checkout URL Parameters (Custom System)

// From src/app/[locale]/(public)/checkout/[priceId]/page.tsx
interface CheckoutParams {
  priceId: string        // Stripe Price ID (required)
  couponCode?: string    // Coupon/discount code
  seats?: number         // Number of seats for team subscriptions
  guest?: 'true'         // Enable guest checkout
  split?: 'true'         // Enable installment payments
}

# Basic checkout
/checkout/price_1234567890

# Guest checkout with coupon
/checkout/price_1234567890?guest=true&couponCode=SAVE20

# Team subscription with 5 seats
/checkout/price_1234567890?seats=5

# Installment checkout for guest
/checkout/price_1234567890?guest=true&split=true

Environment Configuration

Environment-based Selection

# Choose your checkout method
NEXT_PUBLIC_STRIPE_CHECKOUT_TYPE="EmbededForm"    # Recommended
# NEXT_PUBLIC_STRIPE_CHECKOUT_TYPE="ExternalForm"  # Quick setup
# NEXT_PUBLIC_STRIPE_CHECKOUT_TYPE="ReactStripeForm" # Advanced
# NEXT_PUBLIC_STRIPE_CHECKOUT_TYPE="PaymentLink"   # Simple

Method Comparison

Testing Checkout Methods

NEXT_PUBLIC_STRIPE_CHECKOUT_TYPE="EmbededForm"

# Successful payment
4242424242424242

# Declined card
4000000000000002

# Requires authentication
4000002500003155