Skip to content
Create account
 or
Sign in
The Stripe Docs logo
/
Create account
Sign in
OverviewUpgrade your integration
Online payments
OverviewFind your use case
Payment methods
Payment UIs
Payment scenarios
In-person payments
Other Stripe products

Build a checkout page with embedded componentsPublic preview

Use Elements and the Checkout Sessions API to build a checkout page.

Build a checkout page on your website using Stripe Elements and the Checkout Sessions API, an integration that manages tax, discounts, shipping rates, and more.

Set up the server
Server-side

Before you begin, you need to register for a Stripe account.

Use the official Stripe libraries to access the API from your application.

Command Line
npm install stripe@17.4.0-beta.2 --save

Set the SDK to use the custom_checkout_beta=v1 beta version header.

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
import Stripe from 'stripe';
const stripe = new Stripe(
'sk_test_4eC39HqLyjWDarjtT1zdp7dc'
, {
  apiVersion: '2024-12-18.acacia; custom_checkout_beta=v1' as any,
});

Create a Checkout Session
Server-side

Add an endpoint on your server that creates a Checkout Session and returns its client secret to your front end. A Checkout Session represents your customer’s session as they pay for one-time purchases or subscriptions. Checkout Sessions expire 24 hours after creation.

server.ts
import express, {Express} from 'express';

const app: Express = express();

app.post('/create-checkout-session', async (req: Express.Request, res: Express.Response) => {
  const session = await stripe.checkout.sessions.create({
    line_items: [
      {
        price_data: {
          currency: 'usd',
          product_data: {
            name: 'T-shirt',
          },
          unit_amount: 2000,
        },
        quantity: 1,
      },
    ],
    mode: 'payment',
    ui_mode: 'custom',
    // The URL of your payment completion page
    return_url: '{{RETURN_URL}}'
  });

  res.json({clientSecret: session.client_secret});
});

app.listen(3000, () => {
  console.log('Running on port 3000');
});

Set up the front end
Client-side

Install React Stripe.js and the Stripe.js loader from the npm public registry. You need at least version 3.0.0 for React Stripe.js and version 5.2.0 for the Stripe.js loader.

Command Line
npm install --save @stripe/react-stripe-js@^3.0.0 @stripe/stripe-js@^5.2.0

Initialize a stripe instance on your front end with your publishable key, passing in the custom_checkout_beta_5 beta.

App.jsx
import {loadStripe} from '@stripe/stripe-js';
const stripe = loadStripe(
"pk_test_TYooMQauvdEDq54NiTphI7jx"
, {
  betas: ['custom_checkout_beta_5'],
});

Initialize Checkout
Client-side

Retrieve the clientSecret from your server and wrap your application with the CheckoutProvider component.

Use the useCheckout hook in your components to get the checkout object, which contains data from the Checkout Session as well as methods to update it. For now, render the line items as text and log the checkout object to the console to see what’s available.

App.jsx
import React from 'react';
import {CheckoutProvider} from '@stripe/react-stripe-js';
import CheckoutForm from './CheckoutForm';

const App = () => {
  const [clientSecret, setClientSecret] = React.useState(null);
  React.useEffect(() => {
    fetch('/create-checkout-session', {method: 'POST'})
      .then((response) => response.json())
      .then((json) => setClientSecret(json.clientSecret))
  });

  if (clientSecret) {
    return (
      <CheckoutProvider
        stripe={stripe}
        options={{clientSecret}}
      >
        <CheckoutForm />
      </CheckoutProvider>
    );
  } else {
    return null;
  }
};

export default App;
CheckoutForm.jsx
import React from 'react';
import {useCheckout} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  const checkout = useCheckout();
  console.log(checkout);
  return (
    <pre>
      {JSON.stringify(checkout.lineItems, null, 2)}
    </pre>
  )
};

Collect customer email
Client-side

Create a component to collect your customer’s email address. Call updateEmail when your customer finishes the input to validate and save the email address.

  • If you have a multi-step form, call updateEmail before moving to the next step, such as clicking a Save button.
  • If you have a single-page form, call updateEmail before submitting the payment. You can also call updateEmail to validate earlier, such as on input blur.
EmailInput.jsx
import React from 'react';
import {useCheckout} from '@stripe/react-stripe-js';

const EmailInput = () => {
  const checkout = useCheckout();
  const [email, setEmail] = React.useState('');
  const [error, setError] = React.useState(null);

  const handleBlur = () => {
    checkout.updateEmail(email).then((result) => {
      if (result.error) {
        setError(result.error);
      }
    })
  };

  const handleChange = (e) => {
    setError(null);
    setEmail(e.target.value);
  };
  return (
    <div>
      <input
        type="text"
        value={email}
        onChange={handleChange}
        onBlur={handleBlur}
      />
      {error && <div>{error.message}</div>}
    </div>
  );
};

export default EmailInput;

Collect payment details
Client-side

Collect payment details on the client with the Payment Element. The Payment Element is a prebuilt UI component that simplifies collecting payment details for a variety of payment methods.

Customer location
Size
Theme
Layout
To see how Link works for a returning user, enter the email demo@stripe.com. To see how Link works during a new signup, enter any other email and complete the rest of the form.

Mount the PaymentElement component within the CheckoutProvider.

CheckoutForm.jsx
import React from 'react';
import {PaymentElement, useCheckout} from '@stripe/react-stripe-js';

const CheckoutForm = () => {
  const checkout = useCheckout();
  return (
    <form>
      <PaymentElement options={{layout: 'accordion'}}/>
    </form>
  )
};

export default CheckoutForm;

The following props are supported:

You can customize the appearance of all elements by passing elementsOptions.appearance to the CheckoutProvider.

Submit the payment
Client-side

Render a “pay” button that calls confirm to submit the payment.

PayButton.jsx
import React from 'react';
import {useCheckout} from '@stripe/react-stripe-js';

const PayButton = () => {
  const {confirm} = useCheckout();
  const [loading, setLoading] = React.useState(false);
  const [error, setError] = React.useState(null);

  const handleClick = () => {
    setLoading(true);
    confirm().then((result) => {
      if (result.type === 'error') {
        setError(result.error)
      }
      setLoading(false);
    })
  };

  return (
    <div>
      <button disabled={!loading} onClick={handleClick}>
        Pay
      </button>
      {error && <div>{error.message}</div>}
    </div>
  )
};

export default PayButton;

Test your integration

  1. Navigate to your checkout page.
  2. Fill out the payment details with a payment method from the following table. For card payments:
    • Enter any future date for card expiry.
    • Enter any 3-digit number for CVC.
    • Enter any billing postal code.
  3. Submit the payment to Stripe.
  4. Go to the Dashboard and look for the payment on the Payments page. If your payment succeeded, you’ll see it in that list.
  5. Click your payment to see more details, like billing information and the list of purchased items. You can use this information to fulfill the order.
Card numberScenarioHow to test
The card payment succeeds and doesn’t require authentication.Fill out the credit card form using the credit card number with any expiration, CVC, and postal code.
The card payment requires authentication.Fill out the credit card form using the credit card number with any expiration, CVC, and postal code.
The card is declined with a decline code like insufficient_funds.Fill out the credit card form using the credit card number with any expiration, CVC, and postal code.
The UnionPay card has a variable length of 13-19 digits.Fill out the credit card form using the credit card number with any expiration, CVC, and postal code.

See Testing for additional information to test your integration.

See also

Was this page helpful?
YesNo
Need help? Contact Support.
Join our early access program.
Check out our product changelog.
Questions? Contact Sales.
Powered by Markdoc