Stripe Integration Guide: Pick the Right Path First

A person wrapping a ceramic mug in brown paper at a wooden desk next to a closed laptop and a card reader.

A Stripe integration guide comes down to one decision: who renders the payment form. Use Stripe-hosted Checkout or a Payment Link and Stripe handles the card fields, 3D Secure, and most of your PCI burden. Build on the Payment Element or raw API and you own the page, the edge cases, and the bugs. For most small sellers, hosted Checkout plus a webhook handler is the right build.

TL;DR:

  • Pick the integration path before you write code. Payment Links need none, hosted Checkout needs about 20 lines, and the Payment Element needs a full front end and back end.
  • "Hosted" means Stripe serves the page. An iframe means your page embeds Stripe's fields. Both keep card numbers off your server, but only hosted keeps your page out of scope entirely.
  • New integrations should use Checkout Sessions or Payment Intents. The older Charges API is the wrong starting point.
  • The charge call is the easy part. Fulfillment should trigger from a verified webhook, never from the success page redirect.
  • Stripe's standard US rate of 2.9% + 30 cents costs you 6.2% on a $9 sale and 3.05% on a $200 sale, so price points matter more than most guides admit.

Table of Contents

Four Ways to Build a Stripe Integration, and the One I'd Pick

Stripe gives you four routes to a working payment, and every tutorial that ranks for this topic buries the decision under setup steps. Make it first.

Path Code required You host the form? Best for
Payment Links None No One product, no website logic
Hosted Checkout About 20 lines No Most creators and small shops
Embedded Checkout / Payment Element Front end plus back end Yes (Stripe iframes inside your page) Custom branding, upsells, in-page flow
Charges API (legacy) Heavy Yes Nothing new. Avoid

My pick for anyone selling under a few hundred orders a day is hosted Checkout. It handles card validation, wallets, 3D Secure authentication, and localized payment methods without you touching them. The Payment Element looks better inside your page, but it costs you state management, error handling, and a larger test surface. Move to it when you have a measured conversion problem, not before.

If you are selling one product and have no site logic to run, a Payment Link is enough, and you can create one in the dashboard in about two minutes.

Hosted Payment vs Iframe: What the Difference Does to Your PCI Scope

People searching "what is hosted payment and iframe" are asking where card data travels. In a hosted flow, the buyer leaves your domain, pays on a Stripe-served page, and returns. In an iframe flow, the buyer stays on your page, but the card fields are Stripe-served frames embedded in it. In both cases your server never sees a card number.

The compliance difference is small but real. The PCI Security Standards Council publishes several self-assessment questionnaires. SAQ A is the shortest and covers merchants who fully outsource card handling. SAQ A-EP is longer and applies when your own page controls parts of the payment flow, such as a direct-post form. Stripe's documentation states that Checkout and its Elements components are built to keep you in the lighter category. Collecting card numbers in your own form fields puts you in a far heavier one, and there is almost never a reason to do it.

Stripe API Setup: Keys, Test Mode, and a First Python Charge

You need three things before the first call: an account, a pair of keys, and a product with a price.

Keys and modes

Stripe issues a publishable key (starts with pk_) for client-side code and a secret key (starts with sk_) for your server. Test mode and live mode each have their own pair, and the objects in one never appear in the other. Restricted keys (rk_) let you grant narrow permissions, and I would use one in production so a leaked key cannot issue refunds.

Use the test card 4242 4242 4242 4242 with any future expiry and any CVC. Stripe's sample code repositories on GitHub cover most stacks and are the best starting point if you searched for a Stripe integration guide on GitHub.

The first payment in Python

Install the library with pip install stripe, then create a Checkout Session:

import stripe
stripe.api_key = "sk_test_..."

session = stripe.checkout.Session.create(
    mode="payment",
    line_items=[{"price": "price_123", "quantity": 1}],
    success_url="https://example.com/thanks?session_id={CHECKOUT_SESSION_ID}",
    cancel_url="https://example.com/cancel",
)
# Redirect the buyer to session.url

That is the whole charge. The same pattern works in Node, Ruby, PHP, and Go with near-identical shapes.

Why not the Charges API?

Searches for "Stripe integrate charge" lead many readers to the Charges API, and old tutorials still point there. It predates Strong Customer Authentication rules and cannot handle authentication steps cleanly. Stripe's Payment Intents API and Checkout Sessions were built to replace it. If a tutorial calls stripe.Charge.create, close the tab.

Webhooks Are the Real Integration

The redirect to your success page proves nothing. Buyers close tabs, lose connection, and hit back. The only reliable signal that money moved is an event from Stripe, delivered to an endpoint you control. For one-time payments, that event is checkout.session.completed.

Stripe retries failed live-mode webhook deliveries with exponential backoff for up to three days, so an endpoint that was down on Friday can still fulfill Friday's orders on Monday.

That retry window is documented in Stripe's webhook guide, and it means your handler has to tolerate the same event arriving more than once.

What a safe handler does

  • Verifies the signature. Every webhook carries a Stripe-Signature header. Call stripe.Webhook.construct_event(payload, sig_header, endpoint_secret) and reject anything that raises an error.
  • Reads the raw body. Signature checks run against the exact bytes Stripe sent. If your framework parses JSON first and you re-serialize it, verification fails.
  • Stays idempotent. Store the event ID or order ID and skip fulfillment if you have seen it. Stripe also supports an Idempotency-Key header on API requests, so a retried create call does not produce two sessions.
  • Returns a 2xx quickly. Acknowledge first, do slow work (emailing a license key, provisioning access) afterward.

Pro Tip: When signature verification fails in production but works locally, the cause is almost always a middleware layer that consumed or re-encoded the request body, or a test-mode signing secret pasted into a live-mode endpoint. Log the length of the raw payload you receive and compare it to what the Stripe dashboard shows for that delivery. A mismatch points straight at the middleware.

What Stripe Costs You: The Fee Math Before You Commit

Two people at a counter completing a card payment, with a wrapped product being handed across.

Integration guides skip this, and it changes which price points make sense. On the standard US rate listed on Stripe's pricing page (2.9% plus 30 cents per successful online card payment, so check the page for your country), the fixed 30 cents hits cheap products hard.

Sale price Stripe fee Effective rate
$9 $0.56 6.2%
$29 $1.14 3.9%
$50 $1.75 3.5%
$200 $6.10 3.05%

International cards and currency conversion add further percentage points. A $50 sale paid with a non-US card, at the extra 1.5% international surcharge, costs $2.50, or 5%.

Platforms that take their own cut on top of processing cost more. This breakdown of platform fees runs the numbers line by line, and the argument for keeping the whole revenue line follows from them. For your own Stripe setup, bundle sub-$10 items, because the flat fee is the cost you control.

Stripe's effective fee rate by sale price: $9 sale 6.2%; $29 sale 3.9%; $50 sale 3.5%; $200 sale 3.05%

Going Live: A Checklist That Catches the Boring Failures

Most launch-day failures have nothing to do with code. Run through these before you flip the keys.

  • Swap every key and secret. Live publishable key, live secret key, and a live-mode webhook endpoint with its own signing secret.
  • Complete account activation. Stripe will hold payouts until business details and a bank account are verified.
  • Test a decline and a 3D Secure card. Stripe's docs list test numbers that force authentication prompts and failures. Your UI should handle both without a blank screen.
  • Send a real small payment. Charge yourself $1 on a live card, confirm the webhook fires, and refund it.
  • Set the statement descriptor. A buyer who does not recognize the charge name files a dispute instead of emailing you.

Tax and Merchant-of-Record Questions Your Stripe Integration Won't Answer

A direct Stripe integration makes you the seller of record. Stripe moves the money, but it does not automatically decide whether you owe sales tax, VAT, or GST in the buyer's jurisdiction. If you sell digital products across borders, read the rules for indie software sellers before launch, and weigh whether you need a merchant of record. Some sellers do, particularly at low volume across many countries. Many find the tax work manageable once sales justify a bookkeeper.

Skip the Build: Get a Stripe-Connected Checkout Running This Week

Everything above is a few days of work for a developer and a few weeks for someone learning as they go. ReplaPay is a self-hosted checkout license that connects directly to your own Stripe account, with payment links for card and crypto, plus Bitcoin, Lightning, and stablecoin support into your own wallet. The webhook handling, signature checks, and fulfillment logic are already written. It costs $299 once, includes 12 months of updates and 30 days of setup support, and takes no percentage on top of Stripe's fees. The Stripe fee calculator on the site lets you run your own numbers first.

Self-hosted means you run the server and you are the seller of record, so Stripe's processing fees and your tax obligations stay with you. If you sell a handful of items a month, a free Payment Link is cheaper. The license pays for itself when your current platform fees exceed $299, which for many sellers is a single month of sales. Check the spec sheet for supported countries and payout currencies before you buy.

Frequently Asked Questions

What is the simplest way to integrate Stripe into a website?

Create a Payment Link in the Stripe dashboard and paste the URL behind a button. If you need to pass order data or trigger fulfillment, create a hosted Checkout Session from your server and add a webhook endpoint for checkout.session.completed.

Should I use the Charges API or Payment Intents?

Use Payment Intents, or Checkout Sessions, which create them for you. The Charges API is legacy and does not handle authentication steps such as 3D Secure cleanly, so new integrations should not start there.

Can I use the Stripe API with Python?

Yes. Stripe maintains an official Python library installed with pip install stripe. You set your secret key, create a Checkout Session or Payment Intent, and verify webhooks with stripe.Webhook.construct_event.

What is the difference between hosted payment and an iframe?

With a hosted payment page, the buyer pays on a page Stripe serves from its own domain. With an iframe, the buyer stays on your page and Stripe's card fields are embedded in it. Both keep raw card numbers off your server.

Why does my webhook signature verification keep failing?

Usually the request body was altered before verification, often by a framework that parses JSON first. Pass the raw bytes to the verification function, and confirm you are using the signing secret that belongs to the correct endpoint and mode.

Sources