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

Subscriptions is a pricing model where users make recurring payments to use a product. In this integration guide, build a custom payment flow where you render the Payment Element, create a Subscription, and confirm the Subscription 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-authorised 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.

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

You’re ready to collect payment details on the client with the Payment Element. The Payment Element is a pre-built 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.

Note

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

checkout.js
const options = {
  mode: 'subscription',
  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 customise 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.

OptionalCustomise the layout
Client-side

OptionalCustomise the appearance
Client-side

OptionalSave and retrieve customer payment methods

OptionalDynamically update payment details
Client-side

OptionalAdditional Elements options
Client-side

Create the pricing model
Stripe CLI or Dashboard

Create your products and their prices in the Dashboard or with the Stripe CLI.

This example uses a fixed-price service with two different service-level options: Basic and Premium. For each service-level option, you need to create a product and a recurring price. (If you want to add a one-off charge for something like a setup fee, create a third product with a one-off price. To keep things simple, this example doesn’t include a one-off charge.)

In this example, each product bills at monthly intervals. The price for the Basic product is 5 USD. The price for the Premium product is 15 USD.

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: Standard pricing | 15 USD
Basic product: Basic service with minimum features
- Price: Standard pricing | 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’s frontend, collect any necessary user information and pass it to the back-end.

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 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 finalise 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 Finalise 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: {
      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 Subscription
  const res = await fetch("/create-confirm-subscription", {
    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);
});

Create and submit the subscription to Stripe
Server-side

After the customer submits your payment form, use a Subscription to facilitate the confirmation and payment process. On the server, use the customer ID (from a cookie or request parameter), the price ID, and the payment method ID to create and confirm the subscription.

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

const app = express();

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

app.post('/create-confirm-subscription', async (req, res) => {
  const customerId = req.cookies['customer'];
  const confirmationTokenId = req.body.confirmationTokenId;
  // The ID of the Price that you created previously
  const priceId = '{{ PRICE_ID }}';

  try {
    const subscription = await stripe.subscriptions.create({
      customer: customerId,
      items: [{
        price: priceId,
      }],
      payment_behavior: 'default_incomplete',
      payment_settings: { save_default_payment_method: 'on_subscription' },
      expand: ['latest_invoice.payments']
    });

    // Confirm intent with collected payment method
    const {status, clientSecret} = await stripe.paymentIntents.confirm(
      subscription.latest_invoice.payments.data[0].payment.payment_intent,
      {
        confirmation_token: confirmationTokenId,
      }
    );

    res.json({status, clientSecret});
  } 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
JavaScript
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
  }
}

Manage the Subscription

To complete the integration, you might want to listen for webhooks, provision access to your service, and allow customers to cancel their subscriptions. For more details on how to do this, you can refer to the subscriptions integration guide.

Disclose Stripe to your customers

Stripe collects information on customer interactions with Elements to provide services to you, prevent fraud, and improve its services. This includes using cookies and IP addresses to identify which Elements a customer saw during a single checkout session. You’re responsible for disclosing and obtaining all rights and consents necessary for Stripe to use data in these ways. For more information, visit our privacy center.

Finalise 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

Note

Collect addresses

OptionalCustomise the layoutClient-side

OptionalCustomise the appearanceClient-side

OptionalSave and retrieve customer payment methods

OptionalDynamically update payment detailsClient-side

OptionalAdditional Elements optionsClient-side

Create the pricing modelStripe CLI or Dashboard

Create the customerClient and Server

Create the ConfirmationTokenClient-side

Use createPaymentMethod through a legacy implementation

Caution

Create and submit the subscription to StripeServer-side

Handle any next actionsClient-side

Manage the Subscription

Disclose Stripe to your customers

See also

Set up Stripe
Server-side

Collect payment details
Client-side

OptionalCustomise the layout
Client-side

OptionalCustomise the appearance
Client-side

OptionalDynamically update payment details
Client-side

OptionalAdditional Elements options
Client-side

Create the pricing model
Stripe CLI or Dashboard

Create the customer
Client and Server

Create the ConfirmationToken
Client-side

Create and submit the subscription to Stripe
Server-side

Handle any next actions
Client-side