Stripe Embedded Checkout — Pre-Built Payment Page Integration

In this tutorial, you will learn about Stripe Embedded Checkout. We cover key concepts, practical examples, and best practices to help you master this topic.

Stripe Embedded Checkout provides a complete, Stripe-hosted payment page that you embed in your application, handling the entire checkout flow including payment method collection, address collection, and post-payment redirect.

What You'll Learn

• How to create a Checkout Session
• How to embed Checkout in your page
• How to handle the checkout result

Why It Matters

The Payment Element requires frontend development. Embedded Checkout provides a complete, mobile-responsive payment page with address collection, tax calculation, and promo code support—all hosted by Stripe—requiring only a few lines of frontend code.

Real-World Use

DodaTech's SaaS platform uses Embedded Checkout for subscription purchases. Customers click "Buy Now," see a Stripe-hosted page embedded in the site with the product, price, and payment form, complete payment, and are redirected back to their dashboard.

import stripe
from flask import Flask, redirect, jsonify, request

stripe.api_key = 'sk_test_...'

@app.route('/api/create-checkout-session', methods=['POST'])
def create_checkout_session():
    session = stripe.checkout.Session.create(
        line_items=[{
            'price': 'price_abc123',
            'quantity': 1,
        }],
        mode='subscription',
        success_url='https://dodatech.com/dashboard?session_id={CHECKOUT_SESSION_ID}',
        cancel_url='https://dodatech.com/pricing',
        customer_email=request.json.get('email'),
        allow_promotion_codes=True,
        tax_id_collection={'enabled': True}
    )
    return jsonify({'sessionId': session.id})

// Frontend: initialize Embedded Checkout
const stripe = Stripe('pk_test_...');

async function startCheckout() {
  const response = await fetch('/api/create-checkout-session', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ email: 'customer@example.com' })
  });
  const { sessionId } = await response.json();

  const checkout = await stripe.initEmbeddedCheckout({
    clientSecret: sessionId
  });

  checkout.mount('#checkout-container');
}

Subscription Checkout

@app.route('/api/create-subscription-checkout', methods=['POST'])
def create_subscription_checkout():
    session = stripe.checkout.Session.create(
        mode='subscription',
        line_items=[{
            'price': 'price_pro_monthly',
            'quantity': 1
        }],
        subscription_data={
            'trial_period_days': 14,
            'metadata': {'plan': 'pro', 'source': 'website'}
        },
        success_url='https://dodatech.com/subscription/active',
        cancel_url='https://dodatech.com/pricing',
        client_reference_id=request.json.get('user_id'),
        metadata={'user_id': request.json.get('user_id')}
    )
    return jsonify({'url': session.url, 'id': session.id})

Common Mistakes

1. Hardcoding Success/Cancel URLs

Success and cancel URLs must be whitelisted in Stripe dashboard. Use environment-specific URLs.

2. Not Verifying the Checkout Session

Always verify the Checkout Session status on the success page by retrieving it from Stripe with stripe.checkout.Session.retrieve().

3. Forgetting to Handle Mode

Checkout mode must match the use case: payment for one-time, subscription for recurring, setup for saving payment methods.

4. Missing Tax Configuration

Enable tax_id_collection and configure Stripe Tax for automatic tax calculation.

5. Not Testing in Test Mode

Use test mode keys and test card numbers before switching to live mode.

Practice Questions

1. What is Embedded Checkout?
2. How does Embedded Checkout differ from Payment Element?
3. What are the three checkout modes?
4. How do you verify payment on the success page?
5. What is allow_promotion_codes?

Answers

1. A Stripe-hosted payment page embedded in your site. 2. Embedded Checkout is a complete page; Payment Element is a component. 3. payment (one-time), subscription (recurring), setup (save methods). 4. Retrieve the Checkout Session with stripe.checkout.Session.retrieve(). 5. A flag that enables promo code entry on the checkout page.

Challenge

Build a complete checkout flow with Embedded Checkout: product selection page, create Checkout Session, embed checkout, handle success redirect, verify the session, and display order confirmation.

FAQ

Mini Project

Build a complete e-commerce checkout: product catalog page, server-side Checkout Session creation with line items, Embedded Checkout integration, post-payment success page with session verification, and order confirmation email triggered via Webhook.

What's Next

• Learn about SetupIntent for saving payment methods
• Explore subscription management with trials and proration
• Continue to customer portal for self-service billing management