Custom payment forms with the Payment Element

This chapter follows Accepting payments with Stripe Checkout.

Checkout keeps UI on checkout.stripe.com. The Payment Element embeds Stripe’s form in your layout—useful when branding, multi-step flows, or staying on one domain matters. Both paths keep card data off your server via Stripe.js loaded from https://js.stripe.com/v3/.

When you tighten Content Security Policy headers, allow https://js.stripe.com and Stripe’s frame sources per Stripe’s security guide.

Server: create a PaymentIntent

1
import { stripe } from '../stripe-client.js';
2
import { usersById } from '../store.js';
3

4
export async function createPaymentIntent(req, res) {
5
  const { userId, amount, currency } = req.body;
6
  const user = usersById.get(userId);
7

8
  const paymentIntent = await stripe.paymentIntents.create({
9
    amount,
10
    currency: currency ?? 'usd',
11
    customer: user?.stripeCustomerId,
12
    automatic_payment_methods: { enabled: true },
13
    metadata: { appUserId: userId },
14
  });
15

16
  res.json({ clientSecret: paymentIntent.client_secret });
17
}

Amounts are integers in the smallest currency unit. Validate amount on the server against your catalog—never trust client-entered prices.

Browser: load Stripe.js and mount the Element

1
<script src="https://js.stripe.com/v3/"></script>
2
<form id="payment-form">
3
  <div id="payment-element"></div>
4
  <button type="submit">Pay</button>
5
  <p id="message"></p>
6
</form>

1
const publishableKey = 'pk_test_REPLACE_ME';
2
const stripe = Stripe(publishableKey);
3

4
const res = await fetch('/create-payment-intent', {
5
  method: 'POST',
6
  headers: { 'Content-Type': 'application/json' },
7
  body: JSON.stringify({ userId: 'user_1', amount: 1999, currency: 'usd' }),
8
});
9
const { clientSecret } = await res.json();
10

11
const elements = stripe.elements({ clientSecret });
12
elements.create('payment').mount('#payment-element');
13

14
document.getElementById('payment-form').addEventListener('submit', async (e) => {
15
  e.preventDefault();
16
  const { error } = await stripe.confirmPayment({
17
    elements,
18
    confirmParams: {
19
      return_url: `${window.location.origin}/complete.html`,
20
    },
21
  });
22
  if (error) document.getElementById('message').textContent = error.message;
23
});

Serve publishableKey from config rather than hard-coding in source for production.

PaymentIntent statuses and 3D Secure

After confirmation, Stripe may require SCA (3D Secure). confirmPayment handles on-session authentication and redirects to return_url when needed.

Common statuses:

Status	Meaning
`requires_payment_method`	No valid payment method attached
`requires_confirmation`	Ready to confirm
`requires_action`	Customer must complete authentication
`processing`	Payment in flight
`succeeded`	Paid
`canceled`	Canceled

Fulfillment still belongs in webhooks (payment_intent.succeeded), not only on complete.html.

Saving a card during payment

Pass setup_future_usage: 'off_session' when creating the PaymentIntent if this checkout should store the method for later:

1
await stripe.paymentIntents.create({
2
  amount: 1999,
3
  currency: 'usd',
4
  customer: user.stripeCustomerId,
5
  setup_future_usage: 'off_session',
6
  automatic_payment_methods: { enabled: true },
7
});

See Customers in Stripe for off-session charges.

Checkout versus Payment Element

	Checkout	Payment Element
UI location	Hosted by Stripe	Embedded in your pages
Integration effort	Lower	Higher (Stripe.js + styling)
PCI scope	Low (Stripe-hosted fields)	Low when using Elements
Best when	Fast launch, standard checkout	Deep branding, custom flows

Stripe still recommends Checkout Sessions for many new integrations; Payment Element fits when the hosted page is not acceptable.

Next: Webhooks in Stripe.