# Checkout

Stripe Checkout provides hosted payment pages that handle the entire payment flow, from collecting payment information to processing transactions. It supports one-time payments, subscriptions, and setup for future payments with built-in security, mobile optimization, and conversion optimization.

## Capabilities

### Checkout.Sessions

Create and manage hosted checkout sessions:

```typescript { .api }
interface CheckoutSession {
  id: string;
  object: 'checkout.session';
  mode: 'payment' | 'setup' | 'subscription';
  status: 'open' | 'complete' | 'expired';
  url?: string;
  success_url: string;
  cancel_url?: string;
  customer?: string;
  customer_email?: string;
  client_reference_id?: string;
  payment_status: 'paid' | 'unpaid' | 'no_payment_required';
  payment_intent?: string;
  subscription?: string;
  setup_intent?: string;
  amount_total?: number;
  currency?: string;
  expires_at: number;
}

// Create payment session
const session = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items: [
    {
      price_data: {
        currency: 'usd',
        product_data: {
          name: 'T-shirt'
        },
        unit_amount: 2000
      },
      quantity: 1
    }
  ],
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel'
});

// Create subscription session
const subscriptionSession = await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [
    {
      price: 'price_123',
      quantity: 1
    }
  ],
  success_url: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
  cancel_url: 'https://example.com/cancel',
  customer_email: 'customer@example.com'
});

// Create setup session for saving payment methods
const setupSession = await stripe.checkout.sessions.create({
  mode: 'setup',
  customer: 'cus_123',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  payment_method_types: ['card']
});

// Create session with customer creation
const customerSession = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items: [
    {
      price: 'price_123',
      quantity: 1
    }
  ],
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  customer_creation: 'always',
  customer_email: 'new-customer@example.com'
});

// Retrieve session
const retrieved = await stripe.checkout.sessions.retrieve('cs_123', {
  expand: ['line_items']
});

// List sessions
const sessions = await stripe.checkout.sessions.list({
  limit: 10,
  customer: 'cus_123'
});

// Expire session
const expired = await stripe.checkout.sessions.expire('cs_123');

// List line items
const lineItems = await stripe.checkout.sessions.listLineItems('cs_123');
```

## Advanced Configuration

### Automatic Tax Calculation

```typescript { .api }
// Session with automatic tax
const taxSession = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items: [
    {
      price: 'price_123',
      quantity: 1
    }
  ],
  automatic_tax: {
    enabled: true
  },
  customer_update: {
    address: 'auto'
  },
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel'
});
```

### Shipping Address Collection

```typescript { .api }
// Session with shipping
const shippingSession = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items: [
    {
      price: 'price_123',
      quantity: 1
    }
  ],
  shipping_address_collection: {
    allowed_countries: ['US', 'CA', 'GB']
  },
  shipping_options: [
    {
      shipping_rate_data: {
        type: 'fixed_amount',
        fixed_amount: {
          amount: 500,
          currency: 'usd'
        },
        display_name: 'Ground shipping'
      }
    }
  ],
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel'
});
```

### Custom Fields and Consent Collection

```typescript { .api }
// Session with custom fields
const customFieldsSession = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items: [
    {
      price: 'price_123',
      quantity: 1
    }
  ],
  custom_fields: [
    {
      key: 'company_name',
      label: {
        type: 'custom',
        custom: 'Company name'
      },
      type: 'text',
      optional: false
    }
  ],
  consent_collection: {
    terms_of_service: 'required',
    privacy_policy: 'required'
  },
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel'
});
```

### Promotion Codes and Discounts

```typescript { .api }
// Session with promotion codes
const promoSession = await stripe.checkout.sessions.create({
  mode: 'payment',
  line_items: [
    {
      price: 'price_123',
      quantity: 1
    }
  ],
  allow_promotion_codes: true,
  discounts: [
    {
      coupon: 'coupon_123'
    }
  ],
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel'
});
```

### Subscription Trials and Setup

```typescript { .api }
// Subscription with trial
const trialSession = await stripe.checkout.sessions.create({
  mode: 'subscription',
  line_items: [
    {
      price: 'price_123',
      quantity: 1
    }
  ],
  subscription_data: {
    trial_period_days: 14,
    metadata: {
      source: 'checkout'
    }
  },
  payment_method_collection: 'if_required',
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel'
});
```

## Session Webhooks

Handle checkout session events:

```typescript { .api }
// Handle checkout completion
app.post('/webhook', (req, res) => {
  const event = stripe.webhooks.constructEvent(
    req.body,
    req.headers['stripe-signature'],
    endpointSecret
  );

  switch (event.type) {
    case 'checkout.session.completed':
      const session = event.data.object;
      
      if (session.mode === 'payment') {
        // Payment successful
        console.log('Payment completed:', session.payment_intent);
      } else if (session.mode === 'subscription') {
        // Subscription created
        console.log('Subscription created:', session.subscription);
      } else if (session.mode === 'setup') {
        // Payment method saved
        console.log('Setup completed:', session.setup_intent);
      }
      break;
      
    case 'checkout.session.expired':
      const expiredSession = event.data.object;
      console.log('Session expired:', expiredSession.id);
      break;
  }

  res.json({ received: true });
});
```

## Embedded Checkout

For custom integration with your UI:

```typescript { .api }
// Create embedded session
const embeddedSession = await stripe.checkout.sessions.create({
  ui_mode: 'embedded',
  mode: 'payment',
  line_items: [
    {
      price: 'price_123',
      quantity: 1
    }
  ],
  return_url: 'https://example.com/return?session_id={CHECKOUT_SESSION_ID}'
});

// Use client_secret on frontend
const clientSecret = embeddedSession.client_secret;
```

Checkout Sessions provide a complete hosted payment solution with minimal integration effort, handling security, compliance, and conversion optimization automatically while supporting extensive customization options for branding and business logic.