Finalize payments on the server

Build an integration where you render the Payment Element before you create a PaymentIntent or SetupIntent, then confirm the Intent from your server.

The Payment Element allows you to accept multiple payment methods using a single integration. This integration builds a custom payment flow where you render the Payment Element, create the PaymentIntent, and confirm the payment from your server.

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

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.

Collect payment details
Client-side

You’re ready to 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.

The Payment Element contains an iframe that securely sends payment information to Stripe over an HTTPS connection. Avoid placing the Payment Element within another iframe because some payment methods require redirecting to another page for payment confirmation.

The checkout page address 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/basil/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>

When the form above has loaded, create an Elements instance with the mode, amount, and currency. These values determine which payment methods are shown to your customer.

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

checkout.js
const options = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
  paymentMethodCreation: 'manual',
  // 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. To collect a customer’s full billing address (to calculate the tax for digital goods and services, for example) or shipping address, use the Address Element.

OptionalCustomize the layout
Client-side

You can customize the Payment Element’s layout (accordion or tabs) to fit your checkout interface. For more information about each of the properties, see elements.create.

You can start using the layout features by passing a layout type and other optional properties when creating the Payment Element:

const paymentElement = elements.create('payment', {
  layout: {
    type: 'accordion',
    defaultCollapsed: false,
    radios: true,
    spacedAccordionItems: false
  }
});

The following image is the same Payment Element rendered using different layout configurations:

Payment Element layouts

OptionalCustomize the appearance
Client-side

Now that you’ve added the Payment Element to your page, you can customize its appearance to make it fit your design. To learn more about customizing the Payment Element, see Elements Appearance API.

Customize the Payment Element

OptionalSave and retrieve customer payment methods

You can configure the Payment Element to save your customer’s payment methods for future use. This section shows you how to integrate the saved payment methods feature, which enables the Payment Element to:

Prompt buyers for consent to save a payment method
Save payment methods when buyers provide consent
Display saved payment methods to buyers for future purchases
Automatically update lost or expired cards when buyers replace them

The Payment Element and a saved payment method checkbox

Save payment methods.

The Payment Element with a Saved payment method selected

Reuse a previously saved payment method.

Enable saving the payment method in the Payment Element

Create a CustomerSession on your server by providing the Customer ID and enabling the payment_element component for your session. Configure which saved payment method features you want to enable. For instance, enabling payment_method_save displays a checkbox that allows customers to save their payment details for future use.

You can specify setup_future_usage on a PaymentIntent or Checkout Session to override the default behavior for saving payment methods. This ensures that you automatically save the payment method for future use, even if the customer doesn’t explicitly choose to save it.

Caution

Allowing buyers to remove their saved payment methods by enabling payment_method_remove impacts subscriptions that depend on that payment method. Removing the payment method detaches the PaymentMethod from that Customer.

Your Elements instance uses the CustomerSession’s client secret to access that customer’s saved payment methods. Handle errors properly when you create the CustomerSession. If an error occurs, you don’t need to provide the CustomerSession client secret to the Elements instance, as it’s optional.

Create the Elements instance using the CustomerSession client secret. Then, use the Elements instance to create a Payment Element.

checkout.js
// Create the CustomerSession and obtain its clientSecret
const res = await fetch("/create-customer-session", {
  method: "POST"
});

const {
  customer_session_client_secret: customerSessionClientSecret
} = await res.json();

const elementsOptions = {
  mode: 'payment',
  amount: 1099,
  currency: 'usd',
  customerSessionClientSecret,
  // Fully customizable with appearance API.
  appearance: {/*...*/},
};

// Set up Stripe.js and Elements to use in checkout form, passing the client secret
// and CustomerSession's client secret obtained in a previous step
const elements = stripe.elements(elementsOptions);

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

When creating the ConfirmationToken, Stripe.js automatically controls setting setup_future_usage on the ConfirmationToken and allow_redisplay on the PaymentMethod, depending on whether the customer checked the box to save their payment details.

Enforce CVC recollection

Optionally, specify require_cvc_recollection both when creating the PaymentIntent and when creating Elements to enforce CVC recollection when a customer is paying with a card.

Detect the selection of a saved payment method

To control dynamic content when a saved payment method is selected, listen to the Payment Element change event, which is populated with the selected payment method.

checkout.js
paymentElement.on('change', function(event) {
  if (event.value.payment_method) {
    // Control dynamic content if a saved payment method is selected
  }
})

OptionalDynamically update payment details
Client-side

As the customer performs actions that change the payment details (for example, applying a discount code), update the Elements instance to reflect the new values. Some payment methods, like Apple Pay and Google Pay, show the amount in the UI, so make sure it’s always accurate and up to date.

checkout.js
async function handleDiscountCode(code) {
  // On the server, validate that the discount code is valid and return the new amount
  const {newAmount} = await fetch("/apply-discount", {
      method: "POST",
      headers: {"Content-Type": "application/json"},
      body: JSON.stringify({code}),
    });
  elements.update({amount: newAmount});
}

OptionalAdditional Elements options
Client-side

The Elements object accepts additional options that influence payment collection. Based on the options provided, the Payment Element displays available payment methods from those you’ve enabled. Learn more about payment method support.

Property	Type	Description	Required
`mode`	`payment` `setup` `subscription`	Indicates whether the Payment Element is used with a PaymentIntent, SetupIntent, or Subscription.	Yes
`currency`	`string`	The currency of the amount to charge the customer.	Yes
`amount`	`number`	The amount to charge the customer, shown in Apple Pay, Google Pay, or BNPL UIs.	For `payment` and `subscription` mode
`setupFutureUsage`	`off_session` `on_session`	Indicates that you intend to make future payments with the payment details collected by the Payment Element.	No
`captureMethod`	`automatic` `automatic_async` `manual`	Controls when to capture the funds from the customer’s account.	No
`onBehalfOf`	`string`	Connect only. The Stripe account ID, which is the business of record. See use cases to determine if this option is relevant for your integration.	No
`paymentMethodTypes`	`string[]`	A list of payment method types to render. You can omit this attribute to manage your payment methods in the Stripe Dashboard.	No
`paymentMethodConfiguration`	`string`	The payment method configuration to use when managing your payment methods in the Stripe Dashboard. If not specified, your default configuration is used.	No
`paymentMethodCreation`	`manual`	Allows PaymentMethods to be created from the Elements instance using stripe.createPaymentMethod.	No
`paymentMethodOptions`	`{us_bank_account: {verification_method: string}}`	Verification options for the `us_bank_account` payment method. Accepts the same verification methods as Payment Intents.	No
`paymentMethodOptions`	`{card: {installments: {enabled: boolean}}}`	Allows manually enabling the card installment plan selection UI if applicable when you aren’t managing your payment methods in the Stripe Dashboard. You must set `mode='payment'` and explicitly specify `paymentMethodTypes`. Otherwise an error is raised. Incompatible with `paymentMethodCreation='manual'`.	No

Create the ConfirmationToken
Client-side

Use createPaymentMethod through a legacy implementation

If you’re using a legacy implementation, you might be using the information from stripe.createPaymentMethod to finalize payments on the server. While we encourage you to follow this guide to Migrate to Confirmation Tokens you can still access our old documentation to Finalize payments on the server

When the customer submits your payment form, call stripe.createConfirmationToken to create a ConfirmationToken to send to your server for additional validation or business logic before payment confirmation.

Confirming the PaymentIntent generates a PaymentMethod. You can read the payment_method ID off the PaymentIntent confirmation response.

Caution

You must immediately use the created ConfirmationToken to confirm a PaymentIntent; if unused, it expires after 12 hours.

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 ConfirmationToken using the details collected by the Payment Element
  // and additional shipping information
  const {error, confirmationToken} = await stripe.createConfirmationToken({
    elements,
    params: {
      shipping: {
        name: 'Jenny Rosen',
        address: {
          line1: '1234 Main Street',
          city: 'San Francisco',
          state: 'CA',
          country: 'US',
          postal_code: '94111',
        },
      },
      return_url: 'https://example.com/order/123/complete'
    }
  });

  if (error) {
    // This point is only reached if there's an immediate error when
    // creating the ConfirmationToken. Show the error to your customer (for example, payment details incomplete)
    handleError(error);
    return;
  }

  // Create the PaymentIntent
  const res = await fetch("/create-confirm-intent", {
    method: "POST",
    headers: {"Content-Type": "application/json"},
    body: JSON.stringify({
      confirmationTokenId: confirmationToken.id,
    }),
  });

  const data = await res.json();

  // Handle any next actions or errors. See the Handle any next actions step for implementation.
  handleServerResponse(data);
});

OptionalInsert custom business logic
Server-side

Before creating and confirming the payment, you can run your custom business logic. Information about the customer’s payment details is available by looking at the ConfirmationToken you created. If you’re using the Stripe SDK, make sure your SDK is up-to-date to these versions:

stripe-php v13.15.0
stripe-go v76.22.0
stripe-ruby v10.13.0
stripe-java v24.21.0
stripe-node v14.22.0
stripe-python v8.8.0
stripe-dotnet v43.20.0

Create and submit the payment to Stripe
Server-side

When the customer submits your payment form, use a PaymentIntent to facilitate the confirmation and payment process. Create a PaymentIntent on your server with an amount and currency specified. In the latest version of the API, specifying the automatic_payment_methods parameter is optional because Stripe enables its functionality by default. You can manage payment methods from the Dashboard. Stripe handles the return of eligible payment methods based on factors such as the transaction’s amount, currency, and payment flow. To prevent malicious customers from choosing their own prices, always decide how much to charge on the server-side (a trusted environment) and not the client.

You can use the ConfirmationToken sent by your client to create and confirm the PaymentIntent in a single request.

app.js
const stripe = require("stripe")("sk_test_BQokikJOvBiI2HlWgH4olfQ2"
);
const express = require('express');
const app = express();

app.set('trust proxy', true);
app.use(express.json());
app.use(express.static("."));

app.post('/create-confirm-intent', async (req, res) => {
  try {
    const intent = await stripe.paymentIntents.create({
      confirm: true,
      amount: 1099,
      currency: 'usd',
      // In the latest version of the API, specifying the `automatic_payment_methods` parameter is optional because Stripe enables its functionality by default.
      automatic_payment_methods: {enabled: true},
      confirmation_token: req.body.confirmationTokenId, // the ConfirmationToken ID sent by your client
    });
    res.json({
      client_secret: intent.client_secret,
      status: intent.status
    });
  } catch (err) {
    res.json({
      error: err
    })
  }
});

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

Handle any next actions
Client-side

When the PaymentIntent requires additional action from the customer, such as authenticating with 3D Secure or redirecting to a different site, you need to trigger those actions. Use stripe.handleNextAction to trigger the UI for handling customer action and completing the payment.

checkout.js
Select a languageJavaScript
 No results
const handleServerResponse = async (response) => {
  if (response.error) {
    // Show error from server on payment form
  } else if (response.status === "requires_action") {
    // Use Stripe.js to handle the required next action
    const {
      error,
      paymentIntent
    } = await stripe.handleNextAction({
      clientSecret: response.clientSecret
    });

    if (error) {
      // Show error from Stripe.js in payment form
    } else {
      // Actions handled, show success message
    }
  } else {
    // No actions needed, show success message
  }
}

OptionalHandle post-payment events

Stripe sends a payment_intent.succeeded event when the payment completes. Use the Dashboard, a custom webhook, or a partner solution to receive these events and run actions, like sending an order confirmation email to your customer, logging the sale in a database, or starting a shipping workflow.

Listen for these events rather than waiting on a callback from the client. On the client, the customer could close the browser window or quit the app before the callback executes, and malicious clients could manipulate the response. Setting up your integration to listen for asynchronous events also helps you accept more payment methods in the future. Learn about the differences between all supported payment methods.

Handle events manually in the Dashboard
Use the Dashboard to View your test payments in the Dashboard, send email receipts, handle payouts, or retry failed payments.
Build a custom webhook
Build a custom webhook handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.
Integrate a prebuilt app
Handle common business events, such as automation or marketing and sales, by integrating a partner application.

Finalize payments on the server

Build an integration where you render the Payment Element before you create a PaymentIntent or SetupIntent, then confirm the Intent from your server.

Set up StripeServer-side

Enable payment methods

Caution

Collect payment detailsClient-side

Set up Stripe.js

Add the Payment Element to your checkout page

Collect addresses

OptionalCustomize the layoutClient-side

OptionalCustomize the appearanceClient-side

OptionalSave and retrieve customer payment methods

Enable saving the payment method in the Payment Element

Caution

Enforce CVC recollection

Detect the selection of a saved payment method

OptionalDynamically update payment detailsClient-side

OptionalAdditional Elements optionsClient-side

Create the ConfirmationTokenClient-side

Use createPaymentMethod through a legacy implementation

Caution

OptionalInsert custom business logicServer-side

Create and submit the payment to StripeServer-side

Handle any next actionsClient-side

OptionalHandle post-payment events

See also

Set up Stripe
Server-side

Collect payment details
Client-side

OptionalCustomize the layout
Client-side

OptionalCustomize the appearance
Client-side

OptionalDynamically update payment details
Client-side

OptionalAdditional Elements options
Client-side

Create the ConfirmationToken
Client-side

OptionalInsert custom business logic
Server-side

Create and submit the payment to Stripe
Server-side

Handle any next actions
Client-side