Skip to content
Tutorials Center
My learning

Topics

Lesson 13 of 38 ยท Checkout and Payment Intents

The Payment Element and the Client Secret

Build a custom payment page with the Stripe Payment Element. Learn the client secret, server and browser roles, confirmPayment, return_url handling and how to verify results on the server.

Checkout is quick, but it lives on Stripe's page. Sometimes you want the payment form inside your own page, matching your design, with your own surrounding flow. For that, Stripe offers the Payment Element: one prebuilt UI component, rendered in a Stripe-hosted iframe inside your page, that shows the right payment methods for the customer's country and device (cards, wallets, bank debits, buy-now-pay-later and more). The card data goes straight to Stripe from the iframe, so you stay at the lightest PCI tier.

You build it from two halves that cooperate through one value, the client secret.

Server half and browser half

sequenceDiagram
  participant B as Browser
  participant S as Your server
  participant K as Stripe
  B->>S: Page needs a payment (order id)
  S->>K: Create PaymentIntent (amount from your DB)
  K-->>S: intent with client_secret
  S-->>B: client_secret only
  B->>K: Stripe.js mounts Payment Element
  B->>K: confirmPayment(client_secret)
  K-->>B: success / error / redirect
  K->>S: Webhook payment_intent.succeeded

The browser never sees your secret key or decides the amount. It gets only the client secret.

On the server you create the PaymentIntent and return its client_secret:

JavaScript
// Real Stripe usage (read-only).
app.post("/create-payment-intent", async (req, res) => {
  const order = await db.orders.find(req.body.orderId, req.user.id); // ownership check
  const intent = await stripe.paymentIntents.create({
    amount: order.totalCents,
    currency: order.currency,
    automatic_payment_methods: { enabled: true },
    metadata: { order_id: String(order.id) },
  });
  res.json({ clientSecret: intent.client_secret });
});

In the browser you load Stripe.js (always from https://js.stripe.com/v3), create Elements with the client secret, and mount the Payment Element:

HTML
<!-- Real browser code (read-only). -->
<form id="payment-form">
  <div id="payment-element"></div>
  <button id="submit">Pay now</button>
  <div id="error-message"></div>
</form>

<script src="https://js.stripe.com/v3/"></script>
<script>
  const stripe = Stripe("pk_test_YOUR_PUBLISHABLE_KEY");

  async function start() {
    const { clientSecret } = await (await fetch("/create-payment-intent", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ orderId: 1043 }),
    })).json();

    const elements = stripe.elements({ clientSecret });
    elements.create("payment").mount("#payment-element");

    document.getElementById("payment-form").addEventListener("submit", async (event) => {
      event.preventDefault();
      const { error } = await stripe.confirmPayment({
        elements,
        confirmParams: { return_url: "https://example.com/order/complete" },
      });
      if (error) {
        document.getElementById("error-message").textContent = error.message;
      }
    });
  }
  start();
</script>

confirmPayment sends the entered details to Stripe, runs 3D Secure if needed, and then redirects to return_url for methods that need it. If there is an immediate error (declined card), it returns error and the page stays so the customer can fix it. Card payments that need no redirect can use redirect: "if_required".

What the client secret is

The client secret looks like pi_3Ox91Z_secret_AbC.... It lets whoever holds it confirm that one PaymentIntent and read its status, and nothing else. It cannot refund, cannot create other payments, cannot read your customers. Still, treat it as sensitive:

  • Send it only to the customer who owns the order, over HTTPS.
  • Do not log it, put it in URLs that appear in analytics, or store it long term.
  • Never confuse it with the secret API key.

Who holds what

Secret key Server only
Publishable key Browser, harmless
Client secret One intent, one customer
1 / 2

A stand-in of the whole conversation

The following runs the same conversation locally. The "browser" only ever receives a client secret; the "server" owns the amount; the "Stripe" part checks that the secret matches the intent. All three are stand-ins in one program.

Node.js Client secret flow (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Notice the last two lines. The browser saw succeeded, but your order record flips only when your server hears it from Stripe.

Showing the result after the redirect

On return_url Stripe appends payment_intent_client_secret and redirect_status to the URL. Use them to show a message, but do not trust them for fulfilment. A quick pattern: retrieve the intent in the browser with stripe.retrievePaymentIntent(clientSecret) and render a message based on its status.

Node.js Choosing a message from the status (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Appearance and options

Pass an appearance object to stripe.elements to match your brand (colors, fonts, spacing) using a theme such as stripe, night or flat plus variables. You can set layout: "accordion" or "tabs" for the payment-method picker, prefill billing details, or collect the address with a separate Address Element. None of it changes your PCI position, because the fields remain Stripe's.

Dynamic payment methods

With automatic_payment_methods: { enabled: true } the Payment Element shows the methods you enabled in the Dashboard that are eligible for this amount, currency and customer location. Adding a new method later is a Dashboard switch, not a code change. That is the main advantage over hard-coding payment_method_types.

Next: Customers and Saved Payment Methods.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What can someone who has only a PaymentIntent client secret do?

    The client secret is scoped to a single PaymentIntent.
  2. 2. Who decides the amount in this flow?

    The server creates the intent from its own data. The browser only receives the client secret.
  3. 3. The browser reports success after confirmPayment. When should you mark the order paid?

    Browser state can be faked or lost. The server confirms with Stripe.
  4. 4. Why enable automatic_payment_methods?

    Dynamic payment methods let you add methods from the Dashboard.

Summary

  • The Payment Element is a Stripe-hosted iframe inside your page; card data never touches your server.
  • The server creates the PaymentIntent and returns only the client secret.
  • stripe.confirmPayment handles 3D Secure and redirects to return_url.
  • The client secret is scoped to one intent; still keep it private.
  • Fulfil from the webhook, not from the browser.

Next: Customers and Saved Payment Methods