0
# Checkout
1

2
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.
3

4
## Capabilities
5

6
### Checkout.Sessions
7

8
Create and manage hosted checkout sessions:
9

10
```typescript { .api }
11
interface CheckoutSession {
12
  id: string;
13
  object: 'checkout.session';
14
  mode: 'payment' | 'setup' | 'subscription';
15
  status: 'open' | 'complete' | 'expired';
16
  url?: string;
17
  success_url: string;
18
  cancel_url?: string;
19
  customer?: string;
20
  customer_email?: string;
21
  client_reference_id?: string;
22
  payment_status: 'paid' | 'unpaid' | 'no_payment_required';
23
  payment_intent?: string;
24
  subscription?: string;
25
  setup_intent?: string;
26
  amount_total?: number;
27
  currency?: string;
28
  expires_at: number;
29
}
30

31
// Create payment session
32
const session = await stripe.checkout.sessions.create({
33
  mode: 'payment',
34
  line_items: [
35
    {
36
      price_data: {
37
        currency: 'usd',
38
        product_data: {
39
          name: 'T-shirt'
40
        },
41
        unit_amount: 2000
42
      },
43
      quantity: 1
44
    }
45
  ],
46
  success_url: 'https://example.com/success',
47
  cancel_url: 'https://example.com/cancel'
48
});
49

50
// Create subscription session
51
const subscriptionSession = await stripe.checkout.sessions.create({
52
  mode: 'subscription',
53
  line_items: [
54
    {
55
      price: 'price_123',
56
      quantity: 1
57
    }
58
  ],
59
  success_url: 'https://example.com/success?session_id={CHECKOUT_SESSION_ID}',
60
  cancel_url: 'https://example.com/cancel',
61
  customer_email: 'customer@example.com'
62
});
63

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

73
// Create session with customer creation
74
const customerSession = await stripe.checkout.sessions.create({
75
  mode: 'payment',
76
  line_items: [
77
    {
78
      price: 'price_123',
79
      quantity: 1
80
    }
81
  ],
82
  success_url: 'https://example.com/success',
83
  cancel_url: 'https://example.com/cancel',
84
  customer_creation: 'always',
85
  customer_email: 'new-customer@example.com'
86
});
87

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

93
// List sessions
94
const sessions = await stripe.checkout.sessions.list({
95
  limit: 10,
96
  customer: 'cus_123'
97
});
98

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

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

106
## Advanced Configuration
107

108
### Automatic Tax Calculation
109

110
```typescript { .api }
111
// Session with automatic tax
112
const taxSession = await stripe.checkout.sessions.create({
113
  mode: 'payment',
114
  line_items: [
115
    {
116
      price: 'price_123',
117
      quantity: 1
118
    }
119
  ],
120
  automatic_tax: {
121
    enabled: true
122
  },
123
  customer_update: {
124
    address: 'auto'
125
  },
126
  success_url: 'https://example.com/success',
127
  cancel_url: 'https://example.com/cancel'
128
});
129
```
130

131
### Shipping Address Collection
132

133
```typescript { .api }
134
// Session with shipping
135
const shippingSession = await stripe.checkout.sessions.create({
136
  mode: 'payment',
137
  line_items: [
138
    {
139
      price: 'price_123',
140
      quantity: 1
141
    }
142
  ],
143
  shipping_address_collection: {
144
    allowed_countries: ['US', 'CA', 'GB']
145
  },
146
  shipping_options: [
147
    {
148
      shipping_rate_data: {
149
        type: 'fixed_amount',
150
        fixed_amount: {
151
          amount: 500,
152
          currency: 'usd'
153
        },
154
        display_name: 'Ground shipping'
155
      }
156
    }
157
  ],
158
  success_url: 'https://example.com/success',
159
  cancel_url: 'https://example.com/cancel'
160
});
161
```
162

163
### Custom Fields and Consent Collection
164

165
```typescript { .api }
166
// Session with custom fields
167
const customFieldsSession = await stripe.checkout.sessions.create({
168
  mode: 'payment',
169
  line_items: [
170
    {
171
      price: 'price_123',
172
      quantity: 1
173
    }
174
  ],
175
  custom_fields: [
176
    {
177
      key: 'company_name',
178
      label: {
179
        type: 'custom',
180
        custom: 'Company name'
181
      },
182
      type: 'text',
183
      optional: false
184
    }
185
  ],
186
  consent_collection: {
187
    terms_of_service: 'required',
188
    privacy_policy: 'required'
189
  },
190
  success_url: 'https://example.com/success',
191
  cancel_url: 'https://example.com/cancel'
192
});
193
```
194

195
### Promotion Codes and Discounts
196

197
```typescript { .api }
198
// Session with promotion codes
199
const promoSession = await stripe.checkout.sessions.create({
200
  mode: 'payment',
201
  line_items: [
202
    {
203
      price: 'price_123',
204
      quantity: 1
205
    }
206
  ],
207
  allow_promotion_codes: true,
208
  discounts: [
209
    {
210
      coupon: 'coupon_123'
211
    }
212
  ],
213
  success_url: 'https://example.com/success',
214
  cancel_url: 'https://example.com/cancel'
215
});
216
```
217

218
### Subscription Trials and Setup
219

220
```typescript { .api }
221
// Subscription with trial
222
const trialSession = await stripe.checkout.sessions.create({
223
  mode: 'subscription',
224
  line_items: [
225
    {
226
      price: 'price_123',
227
      quantity: 1
228
    }
229
  ],
230
  subscription_data: {
231
    trial_period_days: 14,
232
    metadata: {
233
      source: 'checkout'
234
    }
235
  },
236
  payment_method_collection: 'if_required',
237
  success_url: 'https://example.com/success',
238
  cancel_url: 'https://example.com/cancel'
239
});
240
```
241

242
## Session Webhooks
243

244
Handle checkout session events:
245

246
```typescript { .api }
247
// Handle checkout completion
248
app.post('/webhook', (req, res) => {
249
  const event = stripe.webhooks.constructEvent(
250
    req.body,
251
    req.headers['stripe-signature'],
252
    endpointSecret
253
  );
254

255
  switch (event.type) {
256
    case 'checkout.session.completed':
257
      const session = event.data.object;
258
      
259
      if (session.mode === 'payment') {
260
        // Payment successful
261
        console.log('Payment completed:', session.payment_intent);
262
      } else if (session.mode === 'subscription') {
263
        // Subscription created
264
        console.log('Subscription created:', session.subscription);
265
      } else if (session.mode === 'setup') {
266
        // Payment method saved
267
        console.log('Setup completed:', session.setup_intent);
268
      }
269
      break;
270
      
271
    case 'checkout.session.expired':
272
      const expiredSession = event.data.object;
273
      console.log('Session expired:', expiredSession.id);
274
      break;
275
  }
276

277
  res.json({ received: true });
278
});
279
```
280

281
## Embedded Checkout
282

283
For custom integration with your UI:
284

285
```typescript { .api }
286
// Create embedded session
287
const embeddedSession = await stripe.checkout.sessions.create({
288
  ui_mode: 'embedded',
289
  mode: 'payment',
290
  line_items: [
291
    {
292
      price: 'price_123',
293
      quantity: 1
294
    }
295
  ],
296
  return_url: 'https://example.com/return?session_id={CHECKOUT_SESSION_ID}'
297
});
298

299
// Use client_secret on frontend
300
const clientSecret = embeddedSession.client_secret;
301
```
302

303
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.