Stripe
Stripe lets your store accept card payments through Stripe's hosted Checkout page. You connect your own Stripe account, so funds settle directly to you.
The integration is deliberately card-only — wallets and local payment methods are not enabled — and auto-capture: funds are taken when the shopper completes checkout, with no separate capture step.
Connecting
Settings → Payments → Stripe.
| Credential | Required | Where to find it |
|---|---|---|
| Secret Key | Yes | Stripe Dashboard → Developers → API keys. Starts with sk_. |
| Publishable Key | Yes | Same place. Starts with pk_. |
| Webhook Secret | Effectively yes | Generated when you add the webhook endpoint below. Starts with whsec_. |
The field is optional to save, but TakeTheme can't verify Stripe's signature without it, so incoming events are skipped — and since online orders are created by the webhook, no order is created. Configure it before taking live payments.
Settings
| Setting | Default | What it does |
|---|---|---|
| Send payment confirmation email | on | Emails the customer when payment succeeds |
| Notify on payment failures (emails) | empty | Alerts these addresses when a checkout fails at Stripe |
| Auto mark orders as paid | on | Not currently enforced — a confirmed payment always marks the order paid |
Payment flow
- Shopper picks Stripe at checkout and submits.
- TakeTheme creates a Stripe Checkout Session with the order's line items, shipping, and tax, and redirects them to Stripe's hosted page.
- Shopper pays by card.
- Stripe sends a webhook; the order is created at that moment, already Paid.
- Shopper returns to your store's success or cancel URL.
Checkout Sessions expire one hour after they're created. A shopper who leaves the tab open longer has to start again.
If the shopper abandons on Stripe's page, nothing is created — the attempt appears under Abandoned checkouts. See How payments work.
When you take payment on an order that already exists (for example an invoice you send), the session is linked to that order up front and the webhook simply marks it paid.
Setting up the webhook
In the Stripe Dashboard, go to Developers → Webhooks → Add endpoint and enter:
POST https://<your-api-host>/v1/webhooks/stripe
Then copy the generated signing secret into the Webhook Secret credential above.
TakeTheme acts on three events:
| Event | What happens |
|---|---|
checkout.session.completed | Payment marked paid and the order created |
payment_intent.succeeded | Payment marked paid, order created, timeline updated |
payment_intent.payment_failed | Payment marked failed, with Stripe's decline reason recorded |
Any other event is acknowledged and ignored.
Signatures are verified on every event, and events older than five minutes are rejected — a captured event can't be replayed against your store later. A missing or invalid signature returns 400; anything else is acknowledged with 200 so Stripe doesn't retry a problem it can't fix.
Events carry your store's identity, so an event for one store can never touch another store's orders.
Refunds
Refunding in TakeTheme records the refund against the order — it does not call Stripe's refund API. Issue the refund from your Stripe Dashboard, then record it on the order so your reporting matches. See Refunds.
Testing before launch
Use Stripe's test mode with a test card such as 4242 4242 4242 4242, and place a real checkout through your storefront. That's the only way to exercise the whole path — session, webhook, order.
If you're running the API locally, the Stripe CLI can forward events to your machine:
stripe listen --forward-to localhost:8080/v1/webhooks/stripe
Paste the whsec_… it prints into the store's Webhook Secret so verification passes.
Note that stripe trigger … events are mock payloads with no store attached: TakeTheme verifies the signature and then deliberately does nothing. A real test-mode checkout is what you want.
Troubleshooting
The shopper paid but no order appeared. Almost always a webhook problem: no webhook secret stored, the endpoint URL is wrong, or the secret belongs to a different Stripe environment. Check Developers → Webhooks in Stripe for delivery attempts and their responses.
The webhook returned 200 but nothing happened.
The event carried no store identity — normal for CLI-triggered events — or the store has no matching Stripe configuration. TakeTheme acknowledges to stop retries and logs the reason.
Amounts in Stripe look 100× larger. Stripe works in the smallest currency unit (cents). The charged amount is correct.
Test payments work, live ones don't. Test and live keys aren't interchangeable, and each environment has its own webhook secret. Swap all three credentials together.