
Mini lesson · English
How to accept a payment on your website
Create a test Payment Link, connect it to the supplied page and verify the payment in your provider account without building a payment backend.
Who is this for?
People who want a payment button on a website. The basic route uses a hosted payment page and a coding assistant for the link; server code, database setup and webhook programming are optional advanced work.
Before you start
Your own eligible Stripe account with a sandbox/test environment and the supplied page. A coding assistant can configure the public test link. The basic route does not need Supabase, a secret API key in the browser or a custom server.
Estimated time: 35–53 min
Estimates for the supplied starter files with prerequisite accounts and tools ready. Setup, deployment queues and delivery/DNS waits take additional time. Account eligibility, activation and real business launch are outside this test lab. No real funds or real card details are used.
What you will learn
- Create a clearly identified sandbox checkout link.
- Connect and test the website’s payment button.
- Verify actual paid/cancelled states in the provider rather than trusting a return page.
Step 1
Choose a sandbox payment goal
Start with a hosted checkout rather than collecting card details yourself.
Use your own Stripe test environment and a fictional product/price. Open the supplied page with your assistant and decide what the payment button should describe.
Keep this exercise in test mode. A visitor opening a success address does not prove that any payment occurred.
A concrete example
For illustration, the product could be “Sample digital workshop” with a one-time USD 5 test price. The button should say it opens test checkout; neither the page nor this lesson promises automatic delivery of that product.
Use the supplied public page for a basic hosted Payment Link exercise. Help me create one test product/price in my own Stripe sandbox and put only its public test checkout URL into the page config. Do not set up the optional database/webhook route or use live credentials. Help publish only the intended practice page and verify a test payment in the provider Dashboard. The return page is not proof of payment.Stripe: create a Payment Link · Stripe: testing
Files for this step
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
Inspect individual files (optional)
How it works (optional)
Accept a test payment with a hosted checkout
Start with a provider-hosted test page and a clearly defined success boundary.
A hosted Payment Link lets the provider collect payment details without putting card inputs into your own page. This practice uses only Stripe's sandbox/test environment and test card values.
The website opens checkout, while the server receives signed payment events and records a receipt. The return page is only navigation: anyone can open a URL, so its presence cannot prove payment.
Worked example
Opening success.html directly must create no receipt. A verified paid session from the configured test Payment Link can create one even if the customer never returns to your site.
Stripe: after a Payment Link payment · Stripe: testing
Extra implementation exercise
A user visits /success.html?paid=true. Should your system grant a paid product?
Show a worked solution
No. A query parameter is controlled by the visitor. Use a verified provider event or a server-side provider check tied to the intended transaction.
- Rejects caller-controlled URLs as payment evidence.
- Requires verified provider payment state.
Common mistake
Unlocking a purchase because a success page was opened.
Step 2
Create and connect the test link
Use the provider dashboard and let the assistant edit the page.
Create the one-time test product/price and Payment Link in your own account. Open its public checkout signed out, then give that test URL to your assistant to connect in the supplied public page.
Check the item, amount, currency and test environment before proceeding. Only the public test checkout URL belongs in this page; no private signing or API key is needed for the basic link.
A concrete example
A successful setup opens the product’s public test checkout signed out. A Stripe account-settings page or the unchanged test_REPLACE placeholder is not a usable checkout link.
Try it yourself
Does the website button open the intended sandbox checkout with the correct item and price?
Discuss your answer with the lesson tutor
Show a worked solution
Illustrative check: the website link opens the public test checkout for “Sample digital workshop”, USD 5, without requiring my Stripe account login. Only that public test link is configured in the page; no API key or webhook secret is needed for this basic route.
- Checks the signed-out hosted checkout against the intended product, amount, currency and test mode.
- Uses only the public test Payment Link in the supplied page configuration.
Files for this step
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
How it works (optional)
Configure the separate test checkout
Keep public checkout URLs distinct from server credentials and webhook secrets.
Follow START-HERE.txt to create a one-time test Payment Link, database table and webhook destination. Install the pinned Stripe dependency in this practice project and preserve its generated lockfile.
Put only the public test checkout URL in config.js. Server environment values include the test secret key, the endpoint signing secret, expected Payment Link ID and private database key. This code deliberately rejects live credentials.
For the complete local sequence, open run-locally.txt: prepare the private root environment, link only the practice project and start the Netlify function proxy. server-env.example.txt lists variable names without real secrets. Opening only the HTML cannot run the server.
Worked example
The webhook signing secret proves which endpoint's events you accept. It is not the public Payment Link and not the API key; copying the wrong secret produces a signature failure.
Node.js: supported release status
Extra implementation exercise
Which of these belongs in public/config.js: the test checkout URL or whsec signing secret?
Show a worked solution
Only the public checkout URL belongs there. Keep the webhook secret and provider/database secret keys in server environment variables.
- Keeps signing/API secrets server-side.
- Uses only the public checkout destination in browser code.
Common mistake
Mixing the local forwarding endpoint's secret with the hosted endpoint's secret.
Step 3
Complete one provider test payment
Use the official test instructions and inspect the account result.
Follow Stripe’s linked testing guidance inside the sandbox only. Complete a disposable test checkout, then find its actual payment/session in your account.
Verify the expected amount, currency and paid status there. A completed page flow can still differ from the payment’s final state, especially for methods that settle later.
A concrete example
“Checkout finished” and “payment confirmed paid” are not always the same observation.
Try it yourself
What did the provider record actually report for your test payment?
Discuss your answer with the lesson tutor
Show a worked solution
Illustrative provider result: the matching test payment is marked paid for USD 5, which agrees with the selected test price. If the provider instead reports processing or unpaid, I would record that state rather than call the order paid because the checkout page finished.
- Finds the matching test payment and its actual paid status in the provider account.
- Compares the recorded amount and currency with the selected test price.
Files for this step
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
Inspect individual files (optional)
How it works (optional)
Verify the event and record paid state once
Authenticate the raw payload before interpreting its JSON.
The handler passes the unchanged raw request bytes and Stripe-Signature to the official SDK. Parsing/reformatting JSON before signature verification can change those bytes and break verification.
It accepts only the expected event types, test mode, matching payment_link and payment_status=paid. Delayed methods may complete checkout before payment succeeds, so checkout completion alone is insufficient. A unique session_id makes repeated receipt insertion harmless.
Two different event IDs can describe the same checkout session: for example, checkout completion followed by asynchronous payment success. The session_id primary key plus on_conflict=session_id and resolution=ignore-duplicates make the durable receipt insert repeatable. A failed database write is not swallowed: it returns 503 so the event can be retried.
Worked example
The same paid session delivered twice still has one primary-key value. Database failure returns 503 so delivery can be retried, rather than acknowledging an event whose result was lost.
Stripe: webhook signature verification and retries
Extra implementation exercise
Why can checkout.session.completed with payment_status=unpaid not yet be treated as a paid order?
Show a worked solution
Some payment methods confirm later. Wait for a verified paid state, including the async success event where applicable, before recording a paid receipt.
- Separates checkout completion from settled payment state.
- Waits for the appropriate paid confirmation.
Common mistake
Marking every completed checkout paid regardless of its payment_status.
Step 4
Try cancellation and a direct return page
Check that a visitor cannot manufacture a paid result by navigation.
Start a separate test checkout and leave it without completing payment, or use a cancellation path the hosted checkout actually provides. Separately, open the supplied success.html page directly. Compare both with your provider’s test payment records.
An abandoned checkout may be incomplete or remain open rather than have a literal “canceled” label. Neither action should be reported as a new paid purchase. The basic page does not automatically deliver a product.
A concrete example
Opening success.html or adding paid=true to its URL does not create a matching paid payment in Stripe. Returning to the site and proving payment are separate operations.
Try it yourself
What did cancellation and the direct return-page visit prove, and what did they not prove?
Discuss your answer with the lesson tutor
Show a worked solution
In this illustrative check, the second checkout was left incomplete and had no new paid payment. Opening success.html directly displayed only the return message. Neither action proves a purchase, and the basic page grants no automatic product access.
- Distinguishes canceled or incomplete checkout from a matching paid payment.
- Recognizes that direct return-page access does not prove payment or grant delivery.
Files for this step
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
Inspect individual files (optional)
How it works (optional)
Trace one test payment end to end
Match the checkout session, signed event and stored receipt.
Use only the official test card values in your sandbox checkout. Find the resulting session and webhook delivery in your account, then inspect the private payment_receipts table in the practice project.
Verify amount and currency against that session. Resend the same legitimate event and confirm there is still one row. Try an unsigned request and a direct success-page visit; neither should create a payment record.
Worked example
A 200 webhook response proves the handler acknowledged something. Check the matching receipt and session rather than assuming all events correspond to the intended product.
Extra implementation exercise
The webhook returns 200 for an unrelated event. Does that mean a receipt should exist?
Show a worked solution
No. The handler acknowledges ignored events without a receipt. Only a matching paid test session should create the intended record.
- Understands intentionally ignored events.
- Matches stored state to the specific paid session.
Common mistake
Expecting every acknowledged webhook to represent a new order.
Step 5
Hand over the basic payment route
Finish a useful link without claiming a complete commerce system.
Repeat the website-button and sandbox payment checks after any repair. Save the practice page/link and a redacted record of successful and cancelled or uncompleted attempts.
Before real sales, confirm your eligible business/account, price/currency, terms and operational process. Automatic access, signed events and database recovery belong to the optional advanced material below.
A concrete example
A working hosted checkout button is a valid small result; it is not evidence that an unbuilt fulfillment backend exists.
Try it yourself
Start with these materials
The starter files and test content are supplied. A live verification still requires your own permitted provider account, inbox or domain as listed under prerequisites. Local inspection is possible without them; record the live step as not tested until you actually perform it.
Provide the test route and actual sandbox results, plus anything needed before a real launch.
What to produce Your test checkout link/page and actual sandbox payment/cancellation observations; no real charge.
Discuss your answer with the lesson tutor
Show a worked solution
Illustrative handoff: the page opens the USD 5 workshop test checkout; one matching test payment is paid for USD 5; the abandoned attempt is not paid; directly opening the return page changes neither record. No real charge or automatic product delivery was tested. Before a real launch I still need an eligible account, real terms and a verified delivery process.
- Supplies the configured public test route with payment and incomplete/canceled outcomes.
- States that live charging and automatic fulfillment are outside the completed basic test.
Files for this step
Open or download the files below. When saving a project, keep the folder paths shown in the filenames.
How it works (optional)
Your assignment: rehearse recovery without real charges
A payment workflow must recover from a missed database write.
In the disposable project, temporarily use an invalid database setting and resend your legitimate paid test event. Observe a non-success response and no new receipt. Restore configuration and resend, then verify exactly one matching row.
Explain what remains before selling for real: supported account/business setup, accurate price/currency and terms, durable fulfillment, reconciliation, refunds and operational monitoring. This workshop only records test receipts.
Worked example
If storage fails but the endpoint says “success”, automatic retries may stop before your record exists. Honest failure is part of reliable payment processing.
The complete reference walkthrough is available in reference/assignment-walkthrough.txt. Compare its steps with your own result; fill the test record from observations in your own project.
Extra implementation exercise
Demonstrate a failed storage attempt and successful duplicate-safe recovery.
Show a worked solution
Install dependencies in the separate practice project with npm install; this generates package-lock.json, which you preserve with that project. Use only a test Payment Link and sk_test_ credentials. The public link is not the webhook signing secret.
Find your matching paid test session, its signed webhook delivery and the private receipt with the same session_id, amount and currency. Redeliver that event: the primary key plus ignore-duplicates preference must leave one receipt. An unsigned request or direct success-page visit must create none.
For the failure rehearsal, temporarily change SUPABASE_URL only in the disposable local/server environment to an invalid test target. Redeliver the same legitimate event and observe a retryable failure. Restore the setting, redeliver and verify one durable receipt. Never change production settings or test with a real card.
- Failed persistence does not acknowledge successful processing.
- Recovery creates one receipt; no real payment details or funds are used.
Common mistake
Calling a receipt recorder a complete production commerce system.
Was this lesson useful?
Leave a like, or share it with someone who could use it.
Continue learning
- How to build your first personal website
- How to publish your website from GitHub
- How to connect a custom domain to your website
- How to set up email on your own domain
- How to make your website usable on phones
- How to make website images load faster
- How to get website feedback in your inbox
- How to add email subscriptions to your website
- How to send automated emails from your website
- How to save form submissions in a database
- How to let people sign in to your website
- How to keep a page private
- How to let users edit their profile information
- How to let users upload images
- How to keep API keys out of your frontend
- How to show data from an external API on your website
- How to add an AI chatbot to your website
- How to make a chatbot answer from your own content
- How to add a blog to your website
- How to add search to your website
- How to add another language to your website
- How to help Google find your website
- How to fix your website preview when sharing a link
- How to measure visits and useful actions on your website
- How to let visitors book an appointment
- How to preview website changes before publishing
- How to undo a broken website deployment
- How to back up and restore your website data
- How to find and fix errors on your live website