Stripe

Picture a small bakery that wants to sell bread on its website. Some people order a loaf or two for the weekend. Others want a bread subscription: a fresh loaf every month, paid for automatically. Either way, the bakery has to take money from people it has never met, through a web page, safely.

In a shop, a card reader does that. Online, there is no reader: the buyer types their card details into a page, and a chain of companies passes the request along until a bank says yes or no. This course is about Stripe, a company that handles that chain for you, and the code you write to use it. First, the chain itself.

Cardholder

The person paying, whose name is on the card.

Merchant

The business being paid. Here, the bakery.

Payment

Money moving from the cardholder’s account to the merchant’s.

Issuer

The bank that gave the cardholder their card, and holds their money.

Acquirer

The bank that accepts card payments on the merchant’s behalf.

Card network

The company whose rails connect issuers and acquirers: Visa, Mastercard, American Express and others.

A card payment happens in two steps, even when they look like one. Authorisation asks the issuer “can this card pay €12?”. If yes, the issuer puts a hold on that amount: the money is set aside but hasn’t moved. Capture then tells the issuer “take it now”. Most online shops capture straight after authorising, so the buyer only ever notices one step.

1. Authorisation: the issuer approves and holds the amount.
2. Capture: the merchant claims the held amount.
3. Settlement: over the next day or few, the money travels from issuer to acquirer.
4. Payout: the merchant’s money lands in its bank account.

Every company in the chain takes a small cut, so the merchant receives a little less than the buyer paid. That difference is the fee. Stripe charges one combined fee per successful payment, usually a percentage plus a fixed amount, depending on the country and the card.

Buyers also pay with wallets (Apple Pay, Google Pay: a card stored on a phone), bank debits (money pulled straight from a bank account) and local methods in some countries. Each is a payment method. Some answer in seconds; some, like bank debits, take days to confirm, which your code will have to handle later.

• A card payment involves the cardholder, the merchant, the acquirer, the card network and the issuer.
• The issuer, the cardholder’s bank, approves or declines.
• Authorisation holds the money; capture takes it; settlement and payout move it over days.
• The merchant receives the amount minus fees.
• Payments can be declined, need the buyer to act, or be reversed later.

Signing a deal with an acquiring bank, connecting to every card network and keeping card data safe is far too much for a bakery. A payment processor does all of it and gives you one simple door. Stripe is a processor: it acts as (or works with) the acquirer, talks to the networks, keeps the money for you, and pays it out to your bank.

Payment processor

A company that accepts payments for merchants and handles the banks and networks behind them.

A card number is enough to steal money, so the card industry has a security standard for anyone who handles one: PCI DSS (the Payment Card Industry Data Security Standard). In one sentence: if card numbers pass through your servers, you must prove, with audits and a long list of controls, that nobody can steal them.

The easy way to stay out of that is to never let a card number reach your code. With Stripe, the buyer types their card into a page or a form field that Stripe serves. Your server only ever sees Stripe’s ids and results, never the card.

An API (application programming interface) is a way for one program to ask another to do something. Stripe’s API lives on the web at https://api.stripe.com. Your server (the program that runs your website, on a computer you control) sends it an HTTP request, the same kind of message a browser sends to load a page, and gets an answer back in JSON, a plain text format for data.

1{2  "id": "cus_...",3  "object": "customer",4  "email": "sam@example.com",5  "created": 1767225600,6  "livemode": false7}

API

A set of requests one program can send another, and the answers it gets back.

Server

A program, running on a computer you control, that answers requests from browsers.

JSON

Text that describes data with { } for objects, [ ] for lists, and "key": value pairs.

Stripe models payments as objects: a Customer, a Product, a Price, a Checkout Session, a Payment Intent, a Refund. Each has an id that starts with a short prefix telling you what it is, an object field naming its type, and created, the time it was made, in seconds since 1 January 1970 (a Unix timestamp).

Both keep the card away from your server, and both end the same way: your server learns from Stripe whether the payment succeeded, and only then hands over the bread.

• A payment processor like Stripe connects your shop to banks and card networks.
• PCI DSS is the card industry’s security standard; keeping card numbers off your server keeps you out of most of it.
• Your server talks to Stripe’s API with HTTP requests and gets JSON back.
• Stripe’s objects have ids with prefixes: cus_, price_, cs_, pi_, sub_, evt_.
• Start with Stripe Checkout, the hosted page; your own form with Elements comes later.

Most programming languages store numbers with a fraction, like 8.50, as floating-point numbers: a binary approximation. Approximations are fine for a temperature, but not for money. In JavaScript and TypeScript, adding ten and twenty cents gives a number that is almost thirty.

1console.log(0.1 + 0.2)          // 0.300000000000000042console.log(0.1 + 0.2 === 0.3)  // false3console.log(10 + 20)            // 30, exactly

Integer

A whole number with no fraction: 0, 850, -3.

Floating point

How computers store numbers with fractions: fast, but approximate. Not for money.

So Stripe never takes decimals for money. Every amount is an integer in the currency’s smallest unit: cents for US dollars, cents for euros, pence for pounds. A sourdough loaf at $8.50 is 850. A monthly bread plan at $30.00 is 3000.

A currency is named by a three-letter ISO 4217 code, which Stripe writes in lowercase: usd, eur, gbp, jpy. An amount means nothing without its currency: 1200 is $12 in usd but only ¥1,200 (about $8) in jpy.

Most currencies split into 100 smaller units. A few, called zero-decimal currencies, don’t: the Japanese yen and the Korean won are counted whole, so the integer is the amount. Stripe also has a minimum amount per currency (for US dollars, 50 cents), below which a charge is refused.

Sometimes a calculation does produce a fraction: a 15% discount on a 850-cent loaf is 722.5 cents. Decide how to round, round once, and keep the result as an integer from then on. Math.round rounds to the nearest whole number.

This is the kind of code that runs before you ever call Stripe: your own cart, in your own server, kept in integers from start to finish.

1type Line = { unitAmount: number; quantity: number }2
3function cartTotal(lines: Line[], percentOff = 0): number {4  // TODO: the subtotal in cents, minus the rounded discount5  return 06}

• Floating-point numbers are approximate; never do money in them.
• Stripe amounts are integers in the smallest unit: 850 is $8.50.
• Currencies are lowercase ISO codes; an amount needs its currency.
• Zero-decimal currencies like jpy have no smaller unit.
• Format for people only at the end, with Intl.NumberFormat; round once, deliberately.

Anyone can make a Stripe account at stripe.com with an email address. You don’t need a company or a bank account to start: those are only asked for when you want to take real money. Until then, everything happens in a practice world.

Stripe gives every account a test environment: the same API, the same Dashboard and the same events as the real thing, but with pretend cards and pretend money. Sandboxes are extra test environments, each with its own keys and settings, so you can try things without disturbing anyone. Live mode is the real world, where cards are charged.

Test mode

Stripe’s practice environment: real API, fake money.

Sandbox

A separate test environment with its own keys, objects and settings.

Live mode

Where real cards are charged and real money moves.

The Dashboard is Stripe’s website for your account. Whatever your code creates shows up there, and you can do most things by hand too: refund a payment, look at a customer, read the log of every request your code made.

An API key is a long password that tells Stripe which account a request is for and what it may do. Each environment has its own pair. The prefix tells you which is which and which world it belongs to.

Code shouldn’t contain keys. Instead, it reads them from environment variables: named values the computer gives a program when it starts. On your own machine, they often sit in a file called .env, which you tell git (the tool that tracks your code’s history) to ignore.

1# Never commit this file. Copy keys from the Dashboard.2STRIPE_SECRET_KEY=sk_test_...3STRIPE_PUBLISHABLE_KEY=pk_test_...

1.env

In test mode, real cards are refused. Stripe publishes test card numbers instead, each behaving in a known way. Use any future expiry date, any three-digit security code and any postcode.

• Test mode and sandboxes are practice worlds; live mode moves real money. They share no objects (test mode does share some settings with live).
• The Dashboard shows everything, and lets you do most things by hand.
• Publishable keys (pk_) are public; secret (sk_) and restricted (rk_) keys stay on the server.
• Read keys from environment variables; keep .env out of git; roll a key that leaks.
• Test cards like 4242 4242 4242 4242 make each outcome happen on demand.

Server code for this course is written in TypeScript, JavaScript with types that catch mistakes before the code runs. To run it you need a few tools, all free.

Terminal

A window where you type commands instead of clicking. On macOS it’s Terminal; on Windows, PowerShell or Windows Terminal.

Node.js

A program that runs JavaScript (and, in recent versions, TypeScript) outside a browser.

npm

Node’s package manager: it downloads code other people published, called packages.

Package

A bundle of reusable code, like Stripe’s library, installed into a project.

Open Customers in the Dashboard (in test mode): Sam Baker is there, made by your script. Run the script again and you get a second Sam Baker with a different id. Stripe doesn’t guess that you meant the same person; avoiding duplicates is your job, and a later module shows how.

• Resources follow the web address: /v1/customers is stripe.customers, /v1/checkout/sessions is stripe.checkout.sessions.
• Methods are verbs: create, retrieve, update, list, del.
• Parameters keep Stripe’s snake_case names, like unit_amount, not unitAmount.
• Every method returns a Promise, a value that arrives later, so you await it.

1const sam =  stripe..(customerId)

When Stripe refuses a request, the library throws an error: it stops your code and reports what happened. The error has a type, a message written for developers, and often a param naming the field at fault.

The Dashboard’s developer section lists every request your keys made: what was sent, what came back, and how long it took. When something fails, the log is often the quickest way to see exactly what Stripe received.

• Install with npm install stripe; make a client with new Stripe(key), the key read from the environment.
• Methods follow the API: stripe.customers.create, retrieve, update, list.
• Parameters are snake_case; every call returns a Promise you await.
• Errors have a type and a message; param points at the field at fault.
• The Dashboard logs every request, which is the first place to look when debugging.

Stripe’s catalogue has two objects. A Product is the thing sold: “Sourdough loaf”, with a name, a description and maybe a picture. A Price belongs to one product and says what it costs: a currency, an amount, and whether it’s paid once or again and again. One product can have many prices.

Product

Something you sell, described once.

Price

One way to pay for a product: currency, amount, once or recurring.

Catalogue

All your products and their prices.

The Dashboard’s product catalogue lets you add products and prices by hand, which is perfect for a small shop. Code does the same through the API, which helps when you have many products or want test and live to match exactly.

1const loaf = await stripe.products.create({2  name: 'Sourdough loaf',3  description: 'Baked this morning, 800 g',4  default_price_data: {5    currency: 'usd',6    unit_amount: 8507  }8})9
10console.log(loaf.id, loaf.default_price)

1const monthly = await stripe.prices.create({2  product: breadClub.id,3  currency: 'usd',4  unit_amount: 3000,5  recurring: { interval: 'month' }6})

A price with recurring is billed again and again. interval is day, week, month or year, and interval_count stretches it: { interval: 'week', interval_count: 2 } is every two weeks. Without recurring, a price is one-time: paid once, like a loaf.

Once a price exists, its amount and currency are fixed, because subscriptions and past orders point at it. When flour costs more and a loaf goes to $9.00, you create a new price and archive the old one (active: false): it stays on old orders but can’t be used for new ones.

1const newPrice = await stripe.prices.({2  product: loafId,3  currency: 'usd',4  unit_amount: 5})6await stripe.prices.update(oldPriceId, { : false })

Price ids differ between test and live, and change when you reprice. Hard-coding price_... in your code breaks both times. A lookup key is your own name for a price, like loaf_sourdough, which you can ask for by name in any environment.

1await stripe.prices.create({2  product: loafId,3  currency: 'usd',4  unit_amount: 900,5  lookup_key: 'loaf_sourdough',6  transfer_lookup_key: true7})8
9const { data } = await stripe.prices.list({10  lookup_keys: ['loaf_sourdough'],11  expand: ['data.product']12})

Most objects take metadata: up to 50 string keys and values of your own. Keys can be up to 40 characters, values up to 500. Use it for your ids and labels, like which oven batch a product comes from or your own order number. Never put secrets or card details in it.

1await stripe.products.update(loafId, {2  metadata: { sku: 'SD-800', category: 'bread' }3})

• Products say what; prices say how much, in which currency, once or recurring.
• Recurring prices have an interval and an optional interval_count.
• Prices don’t change: create a new one and archive the old.
• Lookup keys let code find prices by name in any environment.
• Inline price_data suits amounts worked out per order.
• Metadata holds your own string labels: 50 keys, 500 characters each.

A Checkout Session is a payment page Stripe builds for one purchase. Your server creates it, saying what’s being bought. Stripe answers with a url. You send the buyer there; they pay on Stripe’s page, then Stripe sends them back to a page of yours.

The examples use Express, a popular package for writing Node servers (npm install express). A server listens for requests; each route pairs a method and a path, like POST /checkout, with a function that gets the request (what the browser sent) and builds the response (what goes back).

1import express from 'express'2import Stripe from 'stripe'3
4const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)5const app = express()6app.use(express.urlencoded({ extended: false }))7
8app.post('/checkout', async (req, res) => {9  // create a session here (next slide)10})11
12app.listen(3000)

Route

A method and path (POST /checkout) and the code that answers it.

Request

What the browser sent: the path, headers, and a body such as form fields.

Response

What the server sends back: a status code, headers and a body.

Anything the browser sends can be changed by the person using it, with a few clicks in the browser’s developer tools. So a form may say which loaves and how many, but the price must come from your server’s own records.

A redirect is a response that says “go to this other address instead”. Status 303 See Other tells the browser to follow it with a plain GET, which is right after a form POST. Stripe’s page lives at the session’s url, which is only valid for that one session.

• A Checkout Session is one purchase on Stripe’s page, created by your server.
• mode is payment for one-off orders and subscription for recurring ones.
• Line items are a catalogue price or inline price_data, with a quantity.
• Prices come from your server, never the browser.
• Redirect to session.url with a 303; make a new session for each purchase.

The buyer may also simply close the tab, lose their connection, or wander off. Then neither page is ever visited. Keep that in mind: it is why the success page can’t be where the order is fulfilled.

The success page has to know which session just finished. Put the exact text {CHECKOUT_SESSION_ID} in success_url, and when Stripe sends the buyer back it replaces it with the real session id.

https://bakery.example/thanks?session_id={CHECKOUT_SESSION_ID}

https://bakery.example/thanks?session_id=cs_test_...

1success_url: `${origin}/thanks?session_id={CHECKOUT_SESSION_ID}`

Anyone can type /thanks?session_id=... into their browser, and many paying buyers never arrive at all. So the success page only shows what Stripe reports. Recording the order, emailing the receipt and telling the kitchen to bake happen elsewhere: in a webhook, the subject of the next module.

Your server usually makes its own order record before sending the buyer to Stripe. Put that order’s id on the session so you can find it later. client_reference_id holds one id; metadata holds more. The session also makes a Payment Intent, a separate object with its own metadata, which later refunds and disputes refer to.

1const session = await stripe.checkout.sessions.create({2  mode: 'payment',3  line_items: lineItems,4  : order.id,5  : { orderId: order.id },6  payment_intent_data: { metadata: { orderId: order.id } },7  success_url: successUrl,8  cancel_url: cancelUrl9})

A session you retrieve doesn’t include its line items unless you ask: they can be long. Expand them, or list them separately.

1const session = await stripe.checkout.sessions.retrieve(id, {2  expand: ['line_items']3})4for (const item of session.line_items?.data ?? []) {5  console.log(item.quantity, item.description, item.amount_total)6}7
8// or, page by page:9const items = await stripe.checkout.sessions.listLineItems(id)

A buyer who goes back from Stripe’s page has changed their mind or wants to edit the cart. Show the cart again. If they edit it, make a new session; to make sure the old one can’t be paid, you can end it with stripe.checkout.sessions.expire(id).

• success_url and cancel_url bring the buyer back, when they come back at all.
• {CHECKOUT_SESSION_ID} in success_url becomes the session’s id.
• The success page retrieves the session and shows what Stripe says; it grants nothing.
• status says if the page was finished; payment_status says if the money arrived.
• Tie sessions to your orders with client_reference_id and metadata, on the payment too.

Until now, your server asked Stripe things. A webhook turns that around: when something happens on your account, Stripe sends an HTTP POST to an address on your server, saying what happened. That address is your webhook endpoint, and each message carries an event.

• A buyer pays, then closes the tab before reaching the success page.
• A bank payment clears two days later, with nobody on your site.
• A monthly bread club payment renews, or fails, in the middle of the night.
• Someone refunds an order from the Dashboard.

In each case only the webhook tells your server. That is why payments are fulfilled from webhooks.

Webhook

An HTTP request a service sends to your server when something happens.

Endpoint

The address on your server that receives webhooks, like /webhooks/stripe.

Event

Stripe’s record of something that happened (evt_...), with a type and the object involved.

Your endpoint is a public address: anyone could post a fake “paid” event to it. So Stripe signs each delivery with a secret only you and Stripe know, the endpoint’s signing secret (whsec_...). The Stripe-Signature header carries a timestamp and the signature: a code computed from the secret, the timestamp and the exact body. Change one byte and it no longer matches.

constructEvent is the right tool in an app. Writing its check once by hand shows exactly what it proves. Stripe’s v1 signature is an HMAC-SHA256 (a code made from a secret key and a message; without the key, nobody can make a matching one) of the text timestamp.body, keyed by the signing secret and written in hexadecimal. The web’s built-in crypto.subtle can compute it: importKey turns the secret into a key, sign makes the code.

1const key = await crypto.subtle.importKey(2  'raw',                               // the key is plain bytes3  new TextEncoder().encode('a secret'),4  { name: 'HMAC', hash: 'SHA-256' },5  false,                               // can't be exported again6  ['sign']                             // what it may be used for7)8const mac = await crypto.subtle.sign('HMAC', key, bytesOfMessage)

1const bytes = (text: string) => new TextEncoder().encode(text)2const hex = (buffer: ArrayBuffer) =>3  [...new Uint8Array(buffer)]4    .map((byte) => byte.toString(16).padStart(2, '0'))5    .join('')6
7async function sign(secret: string, t: number, payload: string) {8  // TODO: HMAC-SHA256 of `${t}.${payload}`, keyed by the secret9  return ''10}

The Stripe-Signature header looks like t=1767225600,v1=91e6…: comma-separated key=value pairs. There can be more than one v1 (while you roll a secret over, Stripe signs with both), and a v0 you ignore. A delivery is genuine when one v1 matches the signature you compute, and recent when its t is at most 300 seconds old.

1async function sign(secret: string, t: number, payload: string) {2  const bytes = (text: string) => new TextEncoder().encode(text)3  const hmac = { name: 'HMAC', hash: 'SHA-256' }4  const key = await crypto.subtle5    .importKey('raw', bytes(secret), hmac, false, ['sign'])6  const mac = await crypto.subtle7    .sign('HMAC', key, bytes(`${t}.${payload}`))8  return [...new Uint8Array(mac)]9    .map((byte) => byte.toString(16).padStart(2, '0'))10    .join('')11}12
13async function verify(14  payload: string, header: string, secret: string, now: number15): Promise<boolean> {16  // TODO: read t and each v1; check the age; compare signatures17  return false18}

1. In the Dashboard’s developer section, open Webhooks and add an endpoint.
2. Enter its public address, such as https://bakery.example/webhooks/stripe.
3. Choose the events it should receive, only the ones you handle.
4. Reveal its signing secret (whsec_...) and store it as STRIPE_WEBHOOK_SECRET.

• Webhooks are Stripe telling your server what happened, even when nobody is on your site.
• An event has a type and a snapshot of the object in data.object.
• Verify every delivery with constructEvent over the raw body and the signing secret.
• Switch on event.type; handle delayed payments too.
• Answer 2xx once handled or ignored; errors make Stripe retry for days.

A CLI (command-line interface) is a program you use by typing commands. The Stripe CLI talks to your account in test mode: it can forward webhooks to your own computer, make events happen, and show your API requests as they arrive. Install it from Stripe’s docs (on macOS, brew install stripe/stripe-cli/stripe), then connect it to your account.

1stripe login      # opens the browser to link your account2stripe --version  # check it's installed

CLI

A command-line interface: a program you drive by typing commands in a terminal.

Stripe can’t reach localhost, the name your computer uses for itself. stripe listen opens a connection to Stripe, receives your test account’s events, and sends each one to the local address you give it, signed with a secret it prints when it starts.

1stripe listen --forward-to localhost:3000/webhooks/stripe2# > Ready! Your webhook signing secret is whsec_...

1stripe trigger checkout.session.completed2stripe trigger payment_intent.payment_failed3stripe trigger customer.subscription.deleted

trigger creates real test objects in your account (a product, a customer, a payment) so the event really happens, and listen forwards it. The objects are made up, so their metadata won’t match your orders: good for checking your endpoint receives and verifies events, less for testing a full order.

An automated test is code that runs your code and checks the result, so you can rerun every check in seconds. To test a webhook route without Stripe, build an event yourself and sign it with a test secret using generateTestHeaderString.

1const secret = 'whsec_test_secret'2const payload = JSON.stringify({3  id: 'evt_test_1',4  object: 'event',5  type: 'checkout.session.completed',6  data: { object: { id: 'cs_test_1', payment_status: 'paid',7    client_reference_id: 'order_1' } }8})9const header = stripe.webhooks.generateTestHeaderString({10  payload,11  secret12})13const res = await post('/webhooks/stripe', payload, {14  'stripe-signature': header15})16expect(res.status).toBe(200)

Every event has a page in the Dashboard’s developer section: what it contained, which endpoints it was sent to, each attempt, and what your server answered. A failed delivery can be resent from there once you’ve fixed the bug. Events are kept for 30 days.

• stripe login links the CLI to your test account.
• stripe listen --forward-to sends events to your laptop, with its own whsec_....
• stripe trigger makes events happen with made-up objects; stripe logs tail shows requests.
• Unit tests can sign their own payloads with generateTestHeaderString.
• Test forged, duplicate and unknown events, not just the happy path.
• The Dashboard’s event pages show every delivery and let you resend.

Stripe promises to deliver each event at least once, not exactly once. If your server’s 200 gets lost on the way back, Stripe retries, and your handler sees the same event twice. Retries also mean events can arrive late and out of order: a payment_intent.succeeded may land before or after the checkout.session.completed from the same purchase.

• The same event, more than once.
• Events from one purchase, in any order.
• An event hours after it happened, after your server was down.

Idempotent

Safe to repeat: doing it twice has the same effect as doing it once. Pressing a lift’s call button again doesn’t call a second lift.

Here a Map stands in for the orders table and an array for the emails sent. The events have Stripe’s shape, trimmed to what the handler reads. In markPaid, the check and the change run one after the other with no await between them, so nothing can slip in; in a real database, that is the single conditional UPDATE from two slides back.

1type Session = { client_reference_id: string; payment_status: string }2type Event = { id: string; type: string; data: { object: Session } }3
4const orders = new Map<string, 'pending' | 'paid'>()5const receipts: string[] = []6
7function markPaid(orderId: string) {8  // TODO: only a pending order becomes paid and gets a receipt9  orders.set(orderId, 'paid')10  receipts.push(orderId)11}12
13function handle(event: Event) {14  const session = event.data.object15  switch (event.type) {16    case 'checkout.session.completed':17      if (session.payment_status === 'paid') {18        markPaid(session.client_reference_id)19      }20      break21    // TODO: a delayed payment that cleared22  }23}

A second approach is a table of handled event ids, with the id as its primary key (a column the database won’t allow twice). Insert the event’s id first; if the insert fails because it already exists, you’ve seen this event and can stop.

Stripe waits only a short time for your answer before counting it as failed and retrying. So save what matters before answering (if saving fails, answer 500 and Stripe brings the event back), but hand slow jobs, like generating a PDF invoice or calling a delivery service, to a queue: a list of jobs that another process works through.

With a delayed method, checkout.session.completed arrives with payment_status: 'unpaid', and later checkout.session.async_payment_succeeded (or _failed) arrives with the outcome. With a card, completed arrives already paid and no async event follows. One markPaid called from both places handles every case.

• Events arrive at least once, possibly late, in any order.
• Make handlers idempotent: change state with one conditional statement and act only if it changed.
• “Check, then change” in two steps is a race; let the database decide.
• A log of handled event ids stops exact repeats.
• Save before answering; queue slow work; answer quickly.
• Handle delayed payments; one fulfil can serve the webhook and the success page.

Behind every payment is a Payment Intent (pi_...): Stripe’s record of trying to collect one amount, from “we’d like $19.00” through any check with the bank to “paid”. Each actual attempt to move money is a Charge (ch_...); a Payment Intent may have several attempts if a first card is declined. In payment mode, Checkout creates the Payment Intent for you.

With Elements, Stripe’s card fields sit inside your page instead of on Stripe’s. Your server creates a Payment Intent for the amount and sends its client secret to the browser, which uses it to finish that one payment.

1app.post('/pay', express.json(), async (req, res) => {2  const order = await orders.priceCart(req.body.cartId)3  const intent = await stripe.paymentIntents.create({4    amount: order.total,5    currency: 'usd',6    automatic_payment_methods: { enabled: true },7    metadata: { orderId: order.id }8  })9  res.json({ clientSecret: intent.client_secret })10})

Elements

Stripe’s ready-made payment fields that you place in your own web page.

Client secret

A value that lets the browser complete one specific Payment Intent. Not an API key, but still private to that buyer.

Whoever holds a client secret can confirm that payment and read its status. Send it only to the buyer making the payment, over HTTPS. Don’t log it, don’t put it in a URL you’ll share, and don’t store it longer than the payment needs.

In Europe and elsewhere, rules called Strong Customer Authentication (SCA) make many online payments ask for a second check, usually through 3D Secure: a code or a tap in the buyer’s banking app. The Payment Intent goes to requires_action, Stripe.js shows the check, and the payment continues. Checkout and the Payment Element handle this for you.

Module 1 split a payment into authorisation and capture. By default Stripe does both at once. For a custom cake that the bakery confirms the next morning, it can authorise now and capture once it accepts the order: with capture_method: 'manual', the Payment Intent waits in requires_capture. For most cards, a hold not captured within about seven days is released.

1const intent = await stripe.paymentIntents.create({2  amount: 4500,3  currency: 'usd',4  capture_method: ''5})6// later, when the bakery accepts the order:7await stripe.paymentIntents.(intent.id)