Build an integration with an embedded formPublic preview

First, create a Stripe account or sign in.

Use our official libraries to access the Stripe API from your application:

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

By default, Stripe uses your payment methods settings to determine which payment methods the embedded form presents. You can also configure specific payment methods on your Checkout Session using the payment_method_types attribute.

Create a Checkout Session on your server to control the payment flow. The Checkout Session defines your line items, shipping options, and other settings for the payment.

curl https://api.stripe.com/v1/checkout/sessions \
  -u "sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d "line_items[0][price]={{PRICE_ID}}" \
  -d "line_items[0][quantity]=1" \
  -d mode=payment \
  -d ui_mode=form \
  -d return_url={{RETURN_URL}} \
  -d integration_identifier=embedded_web_0001

Set ui_mode to form to integrate with the embedded form. The returned CheckoutSession object includes a client secret, which the client uses to securely display the checkout interface.

The Checkout Sessions API supports an optional integration_identifier parameter you can set when creating a session. Use it to label this form integration with a recognizable name and measure its conversion independently from other Checkout integrations you run.

You can also configure the following options on the CheckoutSession:

• automatic_tax: Enable automatic tax calculation
• automatic_tax[address_collection_precision]: Control billing address collection in embedded forms for tax calculation when automatic tax is enabled
• billing_address_collection: Collect billing addresses
• customer_email: Prefill the customer’s email address
• customer: Prefill customer data from an existing Customer object
• name_collection: Collect your customers’ business name, individual name, or both
• shipping_address_collection: Collect shipping addresses
• shipping_options: Provide shipping rate options
• submit_type: Specify the type of transaction being performed
• phone_number_collection: Collect your customer’s phone number
• tax_id_collection: Collect tax IDs
• allow_promotion_codes: Allow customer-redeemable promotion codes

The embedded form contains an iframe that securely sends the payment information to Stripe over an HTTPS connection.

You can specify the layout to render the embedded form as a single-step or multi-step embedded form.

You can prefill the customer’s email address using one of two approaches, depending on whether you want the email to be editable.

Set the email on the Checkout Session (non-editable)

Pass customer_email when creating the Checkout Session on your server. The email is displayed in the embedded form but the customer can’t change it. You can also pass a Customer ID to the customer field to prefill the email stored on the Customer.

Set a default email on the client (editable)

Pass defaultValues.email when initializing the SDK to prefill an editable email. The customer can modify this value in the embedded form.

<CheckoutFormProvider
  stripe={stripePromise}
  options={{
    clientSecret,
    defaultValues: {
      email: 'customer@example.com',
    },
  }}
>
  <CheckoutForm />
</CheckoutFormProvider>

The Checkout Session you created on the server automatically determines the line items, total amount, and available payment methods. The embedded form uses this information to display the appropriate interface.

import React, {useMemo} from 'react';
import {CheckoutFormProvider, CheckoutForm, useCheckoutForm} from '@stripe/react-stripe-js/checkout';
import {loadStripe} from '@stripe/stripe-js';

const stripePromise = loadStripe('pk_test_TYooMQauvdEDq54NiTphI7jx');

const CheckoutPage = () => {
  const checkoutState = useCheckoutForm();

  if (checkoutState.type === 'error') {
    return <div>Error: {checkoutState.error.message}</div>;
  }

  const onConfirm = (event) => {
    if (checkoutState.type === 'success') {
       checkoutState.checkout.confirm({formConfirmEvent: event});
    }
  };

  return <CheckoutForm onConfirm={onConfirm} />;
};

const App = () => {
  const clientSecret = useMemo(() => (
    fetch('/create-checkout-session', {method: 'POST'})
      .then((response) => response.json())
      .then((json) => json.client_secret)
  ), []);

  return (
    <CheckoutFormProvider
      stripe={stripePromise}
      options={{clientSecret}}
    >
      <CheckoutPage />
    </CheckoutFormProvider>
  );
};

export default App;

const onConfirm = async (event) => {
  if (checkoutState.type === 'success') {
    try {
      await checkoutState.checkout.confirm({formConfirmEvent: event});
    } catch (error) {
      console.error('Payment confirmation error:', error);
    }
  }
};

The Checkout Session defines your line items, shipping options, and other settings for the payment. After a customer confirms payment on the client, handle the result on your server rather than relying on client-side state.

• Webhooks Recommended: Listen for the checkout.session.completed event, which Stripe sends when the payment succeeds. This approach ensures you’re notified even if the customer closes their browser before the redirect.
• Return page: Retrieve the Checkout Session using its ID to check the payment status and show the appropriate result to your customer on the page you set as the return_url.

Learn how to fulfill orders after receiving a payment.

Before you go live, test each payment method integration. Click Pay to complete the payment, which redirects you to the specified return page.

If you see the return page, and the payment appears in the list of successful payments in the Dashboard, your integration is working.