Collect payment details before creating an Intent

Build an integration where you can render the Payment Element prior to creating a PaymentIntent or SetupIntent.

Compare Customers v1 and Accounts v2 references

If your Connect platform uses customer-configured Accounts, use our guide to replace Customer and event references in your code with the equivalent Accounts v2 API references.

Subscriptions is a pricing model where users make recurring payments to access a product. In this integration guide, learn how to build a custom payment flow that enables you to render the Payment Element, create a Subscription, and confirm the payment from the customer’s browser.

Set up Stripe
Server-side

First, create a Stripe account or sign in.

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

Enable payment methods

Caution

This integration path doesn’t support BLIK or pre-authorized debits that use the Automated Clearing Settlement System (ACSS). You also can’t use customer_balance with dynamic payment methods when the deferred intent is created client-side. The client-side deferred-intent flow can’t include a Customer, and customer_balance requires a Customer on the PaymentIntent, so it’s excluded to avoid errors. To use customer_balance, create the PaymentIntent server-side with a Customer and return its client_secret to the client.

View your payment methods settings and enable the payment methods you want to support. You need at least one payment method enabled to create a PaymentIntent.

By default, Stripe enables cards and other prevalent payment methods that can help you reach more customers, but we recommend turning on additional payment methods that are relevant for your business and customers. See Payment method support for product and payment method support, and our pricing page for fees.

For Subscriptions, configure your invoice settings and supported payment methods. To prevent mismatches and errors, your invoice settings must match your Payment Element settings.

Collect payment details
Client-side

Use the Payment Element to securely send payment information collected in an iFrame to Stripe over an HTTPS connection.

Conflicting iFrames

Avoid placing the Payment Element within another iframe because it conflicts with payment methods that require redirecting to another page for payment confirmation.

Your checkout page URL must start with https:// rather than http:// for your integration to work. You can test your integration without using HTTPS, but remember to enable it when you’re ready to accept live payments.

Set up Stripe.js

The Payment Element is automatically available as a feature of Stripe.js. Include the Stripe.js script on your checkout page by adding it to the head of your HTML file. Always load Stripe.js directly from js.stripe.com to remain PCI compliant. Don’t include the script in a bundle or host a copy of it yourself.

checkout.html
<head>
  <title>Checkout</title>
  <script src="https://js.stripe.com/clover/stripe.js"></script>
</head>

Create an instance of Stripe with the following JavaScript on your checkout page:

checkout.js
// Set your publishable key: remember to change this to your live publishable key in production
// See your keys here: https://dashboard.stripe.com/apikeys
const stripe = Stripe('pk_test_TYooMQauvdEDq54NiTphI7jx'
);

Add the Payment Element to your checkout page

The Payment Element needs a place to live on your checkout page. Create an empty DOM node (container) with a unique ID in your payment form:

checkout.html
<form id="payment-form">
  <div id="payment-element">
    <!-- Elements will create form elements here -->
  </div>
  <button id="submit">Submit</button>
  <div id="error-message">
    <!-- Display error message to your customers here -->
  </div>
</form>

After your form loads, create an Elements instance with the mode, amount, and currency. These values determine which payment methods the Element presents to your customer.

Then, create an instance of the Payment Element and mount it to the container DOM node.

Note

The amount passed to the Payment Element should reflect what a customer will be charged immediately. This could either be the first installment of the subscription or 0 if the subscription has a trial period.

checkout.js
const options = {
  mode: 'subscription',
  amount: 1099,
  currency: 'usd',
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form
const elements = stripe.elements(options);

// Create and mount the Payment Element
const paymentElementOptions = { layout: 'accordion'};
const paymentElement = elements.create('payment', paymentElementOptions);
paymentElement.mount('#payment-element');

The Payment Element renders a dynamic form that allows your customer to pick a payment method. The form automatically collects all necessary payments details for the payment method selected by the customer.

You can customize the Payment Element to match the design of your site by passing the appearance object into options when creating the Elements provider.

Collect addresses

By default, the Payment Element only collects the necessary billing address details. Some behavior, such as calculating tax or entering shipping details, requires your customer’s full address. You can:

Use the Address Element to take advantage of autocomplete and localization features to collect your customer’s full address. This helps ensure the most accurate tax calculation.
Collect address details using your own custom form.

OptionalCustomize the layout
Client-side

OptionalCustomize the appearance
Client-side

OptionalSave and retrieve customer payment methods

OptionalAdditional Elements options
Client-side

Create the pricing model
Stripe CLI or Dashboard

Recurring pricing models represent the products or services you sell, how much they cost, what currency you accept for payments, and the service period for subscriptions. To build the pricing model, create products (what you sell) and prices (how much and how often to charge for your products).

This example uses flat-rate pricing with two different service-level options: Basic and Premium. For each service-level option, you need to create a product and a recurring price. To add a one-time charge for something like a setup fee, create a third product with a one-time price.

Each product bills at monthly intervals. The price for the Basic product is 5 USD. The price for the Premium product is 15 USD. See the flat rate pricing guide for an example with three tiers.

Go to the Add a product page and create two products. Add one price for each product, each with a monthly recurring billing period:

Premium product: Premium service with extra features
- Price: Flat rate | 15 USD
Basic product: Basic service with minimum features
- Price: Flat rate | 5 USD

After you create the prices, record the price IDs so you can use them in other steps. Price IDs look like this: price_G0FvDp6vZvdwRZ.

When you’re ready, use the Copy to live mode button at the top right of the page to clone your product from a sandbox to live mode.

Create the customer
Client and Server

Stripe needs a customer for each subscription. In your application frontend, collect any necessary customer information and pass it to the backend.

If you need to collect address details, the Address Element enables you to collect a shipping or billing address for your customers. To learn more, see Address Element.

register.html
<form id="signup-form">
  <label>
    Email
    <input id="email" type="text" placeholder="Email address" value="test@example.com" required />
  </label>

  <button type="submit">
    Register
  </button>
</form>

register.js
const emailInput = document.querySelector('#email');

fetch('/create-customer', {
  method: 'post',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    email: emailInput.value,
  }),
}).then(r => r.json());

On the server, create the Stripe customer object.

Create the subscription
Server-side

When the customer submits your payment form, use a Subscription to facilitate the confirmation and payment process. To create a subscription, you need a Customer and a Price.

Note

If you’re using a multi-currency Price, use the currency parameter to tell the Subscription which of the Price’s currencies to use. (If you omit the currency parameter, then the Subscription uses the Price’s default currency.)

Included on a Subscription is a client secret. Return this value to your client for Stripe.js to use to securely complete the payment process. For subscriptions that don’t collect a payment up front (for example, subscriptions with a free trial period), use the client secret from the pending_setup_intent.

Confirm the subscription
Client-side

Use stripe.confirmPayment or stripe.confirmSetup to confirm the subscription using details from the Payment Element. Indicate where Stripe should redirect the customer after confirmation by providing a return_url to the confirm function. With some payment methods, the customer is redirected to an intermediate site, like a bank authorization page, before being redirected to the return_url. You can also set redirect to if_required to only redirect customers that check out with redirect-based payment methods.

checkout.js
const form = document.getElementById('payment-form');
const submitBtn = document.getElementById('submit');

const handleError = (error) => {
  const messageContainer = document.querySelector('#error-message');
  messageContainer.textContent = error.message;
  submitBtn.disabled = false;
}

form.addEventListener('submit', async (event) => {
  // We don't want to let default form submission happen here,
  // which would refresh the page.
  event.preventDefault();

  // Prevent multiple form submissions
  if (submitBtn.disabled) {
    return;
  }

  // Disable form submission while loading
  submitBtn.disabled = true;

  // Trigger form validation and wallet collection
  const {error: submitError} = await elements.submit();
  if (submitError) {
    handleError(submitError);
    return;
  }

  // Create the subscription
  const res = await fetch('/create-subscription', {
    method: "POST",
  });
  const {type, clientSecret} = await res.json();
  const confirmIntent = type === "setup" ? stripe.confirmSetup : stripe.confirmPayment;

  // Confirm the Intent using the details collected by the Payment Element
  const {error} = await confirmIntent({
    elements,
    clientSecret,
    confirmParams: {
      return_url: 'https://example.com/order/123/complete',
    },
  });

  if (error) {
    // This point is only reached if there's an immediate error when confirming the Intent.
    // Show the error to your customer (for example, "payment details incomplete").
    handleError(error);
  } else {
    // Your customer is redirected to your `return_url`. For some payment
    // methods like iDEAL, your customer is redirected to an intermediate
    // site first to authorize the payment, then redirected to the `return_url`.
  }
});

Manage the subscription

To complete the integration, you may want to:

listen for webhooks
provision access to your service
allow customers to cancel their subscriptions

To learn more, see Build a subscription integration.

Collect payment details before creating an Intent

Build an integration where you can render the Payment Element prior to creating a PaymentIntent or SetupIntent.

Compare Customers v1 and Accounts v2 references

Set up StripeServer-side

Enable payment methods

Caution

Collect payment detailsClient-side

Conflicting iFrames

Set up Stripe.js

Add the Payment Element to your checkout page

Note

Collect addresses

OptionalCustomize the layoutClient-side

OptionalCustomize the appearanceClient-side

OptionalSave and retrieve customer payment methods

OptionalAdditional Elements optionsClient-side

Create the pricing modelStripe CLI or Dashboard

Create the customerClient and Server

Create the subscriptionServer-side

Note

Confirm the subscriptionClient-side

Manage the subscription

See also

Set up Stripe
Server-side

Collect payment details
Client-side

OptionalCustomize the layout
Client-side

OptionalCustomize the appearance
Client-side

OptionalAdditional Elements options
Client-side

Create the pricing model
Stripe CLI or Dashboard

Create the customer
Client and Server

Create the subscription
Server-side

Confirm the subscription
Client-side