Stripe setup

Updated Oct 14, 2026 Payments

Stripe is the fastest gateway to get working in TitanCart and the one we recommend for most stores: a card form on your own checkout page, 3-D Secure handled in place, refunds from the order, and saved cards for subscriptions. Expect about ten minutes end to end.

Edition note: Stripe is available in both TitanCart Lite and TitanCart Pro.

1. Get your API keys

Sign in to the Stripe Dashboard and switch on Test mode for now.
Open Developers → API keys.
Copy the Publishable key (pk_test_…) and the Secret key (sk_test_…).

Stripe has no sandbox switch in TitanCart: the keys decide. Test keys run test payments, live keys run real ones.

2. Add Stripe in TitanCart

Go to Settings → Payment Gateways and click + Add Payment Gateway.
On the General tab choose the Credit / Debit Card (Stripe) gateway, give it the name shoppers will see, an optional Description and Payment instructions, set Status to Active, and save.
Reopen it and go to the Configure tab (it exists after the first save). Paste the Publishable Key and Secret Key. Leave Webhook Signing Secret for step 3.
Save, then click Test Connection. It should say “Stripe connection successful! You are using TEST mode keys.”

Three fields on this tab do nothing today. Payment Type offers “Stripe Checkout (redirect)” and “Card Elements”, but every store uses the inline card form on your checkout page whatever is selected. Currency and Account Country are not read either: Stripe is always charged in the order’s currency. They stay on the form until the multi-currency work gives them a job. Leave them as they are.

3. Register the webhook

Stripe tells your store when a payment succeeds, fails or is refunded through a webhook, and TitanCart refuses unsigned webhooks: until the signing secret is saved, the gateway shows a NEEDS SETUP pill and Stripe’s calls are rejected. Do this step before any test order.

On the gateway’s Configure tab, copy the Webhook URL TitanCart shows. It ends in /wp-json/titancart/v1/webhooks/stripe.
In the Stripe Dashboard (still in Test mode) open Developers → Webhooks → Add endpoint, paste the URL, and select these events:
- payment_intent.succeeded
- payment_intent.payment_failed
- charge.refunded
Other events are accepted and ignored.
Click Add endpoint, open it, and reveal its Signing secret (whsec_…). This is not the restricted key on the API keys page.
Paste it into Webhook Signing Secret in TitanCart and save. The NEEDS SETUP pill goes away.

4. Place a test order

On your storefront add a product, go to checkout and choose the Stripe gateway. The card form is on the page itself. Use one of Stripe’s test cards:

4242 4242 4242 4242 — succeeds. Any future expiry, any CVC, any postcode.
4000 0025 0000 3155 — asks for 3-D Secure; complete the test challenge on the page.
4000 0000 0000 9995 — declined (insufficient funds), to see the error shoppers get.

After a successful card the browser lands on the order-received page and the order reads Processing under Sales → Orders with the gateway’s name as the payment method. Stock is reduced, the cart emptied, any coupon used, any digital gift card issued, and the confirmation and new-order emails sent — on the confirmed payment, never before it.

What keeps an order honest when the browser disappears

A card is charged on Stripe’s side the moment the shopper confirms. TitanCart commits the order from two independent directions: the checkout page when it returns, and the webhook when Stripe reports the payment. If a shopper closes the tab the instant the charge clears and the webhook is not configured, a third path catches it: Settings → General Settings → Order Automation → Complete paid orders the checkout page never finished asks Stripe once an hour about placed-but-unfinished orders and commits the ones Stripe says are paid. A declined or abandoned checkout leaves a Pending order that Cancel unpaid orders automatically clears after the set hours (24 by default).

5. Switch to live

Switch the Stripe Dashboard out of Test mode and copy the live Publishable key (pk_live_…) and Secret key (sk_live_…).
Live mode has its own webhooks: add the same endpoint URL and the same three events in live mode, and copy its new signing secret.
In TitanCart replace all three values on the Configure tab and save.
Click Test Connection: “You are using LIVE mode keys — real charges will be processed.”
Place one small real order and refund it from the order.

6. Refunds, saved cards, marketplaces

Refunds — refund a Stripe order from the order in Sales → Orders, in full or in part. A refund made in the Stripe Dashboard instead is reported back by the charge.refunded webhook and recorded on the order too.
Subscriptions — with the Subscriptions extension, Stripe saves the card at the first payment and charges renewals off-session. A subscription that starts later with nothing to pay today also works: Stripe saves the card without charging it. See Subscriptions & Recurring.
Marketplace — with the TitanCart Marketplace extension, vendor payouts run through Stripe Connect, which has its own webhook endpoint and signing secret on the same tab. See Marketplace setup.
Wallets — Apple Pay and Google Pay are not offered by this gateway; shoppers type a card.

How to verify on Stripe’s side

Every TitanCart payment reaches Stripe with the description “Order TC-…” and the order number in its metadata. In the Stripe Dashboard → Payments (Test mode on for test orders) search by that order number, the amount or the date. The payment’s page shows the charge, Stripe’s fee, any refund, and under Events whether the webhook delivery to your store succeeded. Developers → Webhooks → your endpoint lists every delivery attempt with the response code your site returned: a 401 means the signing secret in TitanCart does not match.

Troubleshooting

The gateway shows NEEDS SETUP. The Publishable Key, Secret Key or Webhook Signing Secret is empty.
Order stuck in Pending after a successful test card. Almost always the webhook: open the endpoint in Stripe’s Webhooks page and read the last attempt. 401 = wrong or missing signing secret; a timeout = a firewall or basic-auth password in front of a staging site. The hourly Order Automation check will still commit a paid order, but fix the webhook.
“Invalid API key provided”. A test key saved next to a live key, or a key copied with a space. Re-copy both from the same mode of the Dashboard; Test Connection tells you which mode the saved keys are.
The card form doesn’t appear at checkout. The Publishable Key is missing or wrong (the form is built from it), or the gateway is Disabled.
A shopper’s card was declined. The message on the checkout page comes from Stripe; the order stays Pending and is cleared by Order Automation. Nothing was charged.
I chose “Stripe Checkout” but shoppers still see a card form on my page. That is the only mode there is; the field is inert.