Checkout Sessions

Use hosted checkout for secure, PCI-compliant payment collection

Checkout Sessions provide a hosted payment page that handles payment collection, card validation, and 3D Secure authentication. They're the fastest way to start accepting payments.

How It Works

Create a Checkout Session

Your server creates a session with line items and redirect URLs

Redirect to Checkout

Redirect the customer to the hosted checkout page

Customer Pays

Customer enters payment details on the secure page

Confirmation

Customer is redirected to your success URL with session details

Webhook (Optional)

Receive a checkout.session.completed webhook

Creating a Checkout Session

const session = await client.checkout.sessions.create({
  // Associate with an existing customer (optional)
  customerId: 'cus_xxxxxxxx',
  
  // Line items to purchase
  lineItems: [
    {
      productId: 'prod_xxxxxxxx',
      quantity: 1,
    },
  ],
  
  // Where to redirect after checkout
  successUrl: 'https://yourapp.com/success?session_id={CHECKOUT_SESSION_ID}',
  cancelUrl: 'https://yourapp.com/cancel',
  
  // Optional: Allow promo codes
  allowPromotionCodes: true,
  
  // Optional: Collect billing address
  billingAddressCollection: 'required',
});

// Redirect customer to checkout
return redirect(session.data.url);

The {CHECKOUT_SESSION_ID} placeholder in your success URL will be replaced with the actual session ID.

Session Modes

Mode	Description	Use Case
`payment`	One-time payment	Single purchases, one-time fees
`subscription`	Recurring payment	Subscriptions, memberships
`setup`	Save payment method only	Collect card for future use

Subscription Checkout

For recurring products, the session automatically creates a subscription:

const session = await client.checkout.sessions.create({
  mode: 'subscription',
  customerId: 'cus_xxxxxxxx',
  lineItems: [
    {
      productId: 'prod_monthly_plan', // Recurring product
      quantity: 1,
    },
  ],
  subscriptionData: {
    trialDays: 14,  // Optional: Add a trial period
  },
  successUrl: 'https://yourapp.com/welcome',
  cancelUrl: 'https://yourapp.com/pricing',
});

Customizing Checkout

Customize the checkout appearance in your dashboard under Settings → Branding:

Logo and brand colors
Custom fonts
Background images
Form field labels
Submit button text

Handling Success

When a customer completes checkout, they're redirected to your success URL. Retrieve the session to verify payment:

// In your success page handler
const sessionId = searchParams.get('session_id');

const session = await client.checkout.sessions.retrieve(sessionId);

if (session.data.paymentStatus === 'paid') {
  // Payment successful - fulfill the order
  const customerId = session.data.customerId;
  const subscriptionId = session.data.subscriptionId;
  
  await fulfillOrder(session.data);
}

Don't rely solely on the success redirect. Use webhooks to handle payment confirmation for critical fulfillment logic.

🔄