Accept a payment

Securely accept payments online.

Build a payment form or use a prebuilt checkout page to start accepting online payments.

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

This demo only displays Google Pay or Apple Pay if you have an active card with either wallet.

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.

Set the SDK to use at least the 2025-03-31.basil API version.

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.

Set up the front end
Client-side

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.

You’ll need to update Stripe.js to basil from v3 by including the following script tag <script src="https://js.stripe.com/basil/stripe.js"></script>. Learn more about Stripe.js versioning.

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

Note

Stripe provides an npm package that you can use to load Stripe.js as a module. See the project on GitHub. Version 7.0.0 or later is required.

Initialize stripe.js.

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'
,
);

Initialize Checkout
Client-side

Create a fetchClientSecret function. This function retrieves the client secret from your server and returns a promise that resolves with the client secret. Call initCheckout, passing in fetchClientSecret. initCheckout returns a promise that resolves to a checkout instance.

The checkout object acts as the foundation of your checkout page, and contains data from the Checkout Session and methods to update the Session.

The object returned by checkout.session() contains your pricing information. We recommend reading and displaying the total, and lineItems from the session in your UI.

This lets you turn on new features with minimal code changes. For example, adding manual currency prices requires no UI changes if you display the total.

checkout.js
const fetchClientSecret = () => {
  return fetch('/create-checkout-session', {method: 'POST'})
    .then((response) => response.json())
    .then((json) => json.checkoutSessionClientSecret);
};
stripe.initCheckout({fetchClientSecret})
  .then((checkout) => {
    const checkoutContainer = document.getElementById('checkout-container');
    checkoutContainer.append(JSON.stringify(checkout.lineItems, null, 2));
    checkoutContainer.append(document.createElement('br'));
    checkoutContainer.append(`Total: ${checkout.session().total.total.amount}`);
  });

index.html
<div id="checkout-container"></div>

Collect customer email
Client-side

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

Depending on the design of your checkout form, you can call updateEmail in the following ways:

Directly before submitting the payment. You can also call updateEmail to validate earlier, such as on input blur.
Before transitioning to the next step, such as clicking a Save button, if your form includes multiple steps.

index.html
<input type="text" id="email" />
<div id="email-errors"></div>

checkout.js
stripe.initCheckout({fetchClientSecret}).then((checkout) => {
  const emailInput = document.getElementById('email');
  const emailErrors = document.getElementById('email-errors');

  emailInput.addEventListener('input', () => {
    // Clear any validation errors
    emailErrors.textContent = '';
  });

  emailInput.addEventListener('blur', () => {
    const newEmail = emailInput.value;
    checkout.updateEmail(newEmail).then((result) => {
      if (result.error) {
        emailErrors.textContent = result.error.message;
      }
    });
  });
});

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.

First, create a container DOM element to mount the Payment Element. Then create an instance of the Payment Element using checkout.createPaymentElement and mount it by calling element.mount, providing either a CSS selector or the container DOM element.

index.html
<div id="payment-element"></div>

checkout.js
const paymentElement = checkout.createPaymentElement();
paymentElement.mount('#payment-element');

See the Stripe.js docs to view the supported options.

You can customize the appearance of all Elements by passing elementsOptions.appearance when initializing Checkout on the front end.

Submit the payment
Client-side

Render a Pay button that calls confirm from the checkout instance to submit the payment.

index.html
<button id="pay-button">Pay</button>
<div id="confirm-errors"></div>

checkout.js
stripe.initCheckout({fetchClientSecret}).then((checkout) => {
  const button = document.getElementById('pay-button');
  const errors = document.getElementById('confirm-errors');
  button.addEventListener('click', () => {
    // Clear any validation errors
    errors.textContent = '';

    checkout.confirm().then((result) => {
      if (result.type === 'error') {
        errors.textContent = result.error.message;
      }
    });
  });
});

Test your integration

Navigate to your checkout page.
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.
Submit the payment to Stripe.
Go to the Dashboard and look for the payment on the Transactions page. If your payment succeeded, you’ll see it in that list.
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 number	Scenario	How 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.

OptionalCreate products and prices

Before you create a Checkout Session, you can create Products and Prices upfront. Use products to represent different physical goods or levels of service, and Prices to represent each product’s pricing.

For example, you can create a T-shirt as a product with a price of 20 USD. This allows you to update and add prices without needing to change the details of your underlying products. You can either create products and prices with the Stripe Dashboard or API. Learn more about how products and prices work.

The API only requires a name to create a Product. Checkout displays the product name, description, and images that you supply.

Next, create a Price to define how much to charge for your product. This includes how much the product costs and what currency to use.

Each price you create has an ID. When you create a Checkout Session, reference the price ID and quantity. If you’re selling in multiple currencies, make your Price multi-currency. Checkout automatically determines the customer’s local currency and presents that currency if the Price supports it.

OptionalPrefill customer data
Server-side

If you’ve already collected your customer’s email and want to prefill it in the Checkout Session for them, pass customer_email when creating a Checkout Session.

OptionalSave payment method details

Learn how to accept a payment and save your customer’s payment details for future purchases.

OptionalListen for Checkout Session changes

Listen for Checkout Session changes

You can listen for changes to the Checkout Session by adding an event listener on the change event with checkout.on.

checkout.js
checkout = await stripe.initCheckout({
  fetchClientSecret: () => promise,
  elementsOptions: { appearance },
});

checkout.on('change', (session) => {
  // Handle changes to the checkout session
});

OptionalCollect billing and shipping addresses

Collect a billing address

By default, a Checkout Session collects the minimal billing details required for payment through the Payment Element.

Using the Billing Address Element

You can collect complete billing addresses using the Billing Address Element.

First, pass billing_address_collection=required when you create the Checkout Session.

Create a container DOM element to mount the Billing Address Element. Then create an instance of the Billing Address Element using checkout.createBillingAddressElement and mount it by calling element.mount, providing either a CSS selector or the container DOM element.

index.html
<div id="billing-address"></div>

checkout.js
const billingAddressElement = checkout.createBillingAddressElement();
billingAddressElement.mount('#billing-address');

The Billing Address Element supports the following options:

Using a custom form

You can build your own form to collect billing addresses.

If your checkout page has a distinct address collection step before confirmation, call updateBillingAddress when your customer submits the address.
Otherwise, you can submit the address when your customer clicks the “pay” button by passing billingAddress to confirm.

Collect partial billing addresses

To collect partial billing addresses, such as only the country and postal code, pass billing_address_collection=auto.

When collecting partial billing addresses, you must collect addresses manually. By default, the Payment Element automatically collects the minimal billing details required for payment. To avoid double collection of billing details, pass fields.billingDetails=never when creating the Payment Element. If you only intend to collect a subset of billing details (such as the customer’s name), pass never for only the fields you intend to collect yourself.

Collect a shipping address

To collect a customer’s shipping address, pass the shipping_address_collection parameter when you create the Checkout Session.

When you collect a shipping address, you must also specify which countries to allow shipping to. Configure the allowed_countries property with an array of two-letter ISO country codes.

How to use the Shipping Address Element

You can collect complete shipping addresses with the Shipping Address Element.

Create a container DOM element to mount the Shipping Address Element. Then create an instance of the Shipping Address Element using checkout.createShippingAddressElement and mount it by calling element.mount, providing either a CSS selector or the container DOM element.

index.html
<div id="shipping-address"></div>

checkout.js
const shippingAddressElement = checkout.createShippingAddressElement();
shippingAddressElement.mount('#shipping-address');

The Shipping Address Element supports the following options:

Listen for Checkout Session changes

You can listen for changes to the Checkout Session by adding an event listener to handle address-related changes.

Use the Session object to render the shipping amount in your checkout form.

index.html
<div>
  <h3> Totals </h3>
  <div id="subtotal" ></div>
  <div id="shipping" ></div>
  <div id="total" ></div>
</div>

checkout.js
stripe.initCheckout({clientSecret}).then((checkout) => {
  const subtotal = document.getElementById('subtotal');
  const shipping = document.getElementById('shipping');
  const total = document.getElementById('total');

  checkout.on('change', (session) => {
    subtotal.textContent = `Subtotal: ${session.total.subtotal.amount}`;
    shipping.textContent = `Shipping: ${session.total.shippingRate.amount}`;
    total.textContent = `Total: ${session.total.total.amount}`;
  })
})

Use a custom form

You can build your own form to collect shipping addresses.

If your checkout page has a distinct address collection step before confirmation, call updateShippingAddress when your customer submits the address.
Otherwise, you can submit the address when your customer clicks the “pay” button by passing shippingAddress to confirm.

OptionalSeparate authorization and capture
Server-side

Stripe supports two-step card payments so you can first authorize a card, then capture funds later. When Stripe authorizes a payment, the card issuer guarantees the funds and places a hold for the payment amount on the customer’s card. You then have a certain amount of time to capture the funds, depending on the card). If you don’t capture the payment before the authorization expires, the payment is cancelled and the issuer releases the held funds.

Separating authorization and capture is useful if you need to take additional actions between confirming that a customer is able to pay and collecting their payment. For example, if you’re selling stock-limited items, you may need to confirm that an item purchased by your customer using Checkout is still available before capturing their payment and fulfilling the purchase. Accomplish this using the following workflow:

Confirm that Stripe authorized the customer’s payment method.
Consult your inventory management system to confirm that the item is still available.
Update your inventory management system to indicate that a customer has purchased the item.
Capture the customer’s payment.
Inform your customer whether their purchase was successful on your confirmation page.

To indicate that you want to separate authorization and capture, you must set the value of payment_intent_data.capture_method to manual when creating the Checkout Session. This instructs Stripe to only authorize the amount on the customer’s card.

To capture an uncaptured payment, you can use either the Dashboard or the capture endpoint. Programmatically capturing payments requires access to the PaymentIntent created during the Checkout Session, which you can get from the Session object.

OptionalCustomer account management
No code

Let your customers manage their own accounts by sharing a link to your customer portal. The customer portal lets customers log in with their email to manage subscriptions, update payment methods, and so on.

OptionalOrder fulfillment

Learn how to programmatically get a notification when a customer pays.

Accept a payment

Securely accept payments online.

Set up the serverServer-side

Create a Checkout SessionServer-side

Set up the front endClient-side

Note

Initialize CheckoutClient-side

Collect customer emailClient-side

Collect payment detailsClient-side

Submit the paymentClient-side

Test your integration

OptionalCreate products and prices

OptionalPrefill customer dataServer-side

OptionalSave payment method details

OptionalListen for Checkout Session changes

Listen for Checkout Session changes

OptionalCollect billing and shipping addresses

Collect a billing address

Using the Billing Address Element

Using a custom form

Collect partial billing addresses

Collect a shipping address

How to use the Shipping Address Element

Listen for Checkout Session changes

Use a custom form

OptionalSeparate authorization and captureServer-side

OptionalCustomer account managementNo code

OptionalOrder fulfillment

See also

Set up the server
Server-side

Create a Checkout Session
Server-side

Set up the front end
Client-side

Initialize Checkout
Client-side

Collect customer email
Client-side

Collect payment details
Client-side

Submit the payment
Client-side

OptionalPrefill customer data
Server-side

OptionalSeparate authorization and capture
Server-side

OptionalCustomer account management
No code