Skip to content
Gaurav TiwariDocs

Set Up Stripe Payments

Updated November 7, 2026

Taking cards in WooCommerce often means one plugin for Stripe, another for Apple Pay buttons and a third for subscriptions, each with its own settings screen and webhook. When a renewal fails, you’re left checking three logs to find out why.

The Stripe module is a Stripe gateway built into Stackless. It runs the Stripe Payment Element on the block and classic checkout, saves cards, shows Apple Pay, Google Pay and Link buttons, refunds from the order screen, and charges subscription renewals off-session.

Turn On the Gateway

Setup lives in two places:

  1. Switch on the Stripe module under Stackless → Dashboard.
  2. Add your keys under Stackless → Settings → Stripe.
  3. Tick Enable Stripe under WooCommerce → Settings → Payments → Stripe (Stackless).

The WooCommerce payments screen only holds the on/off switch, with an Open Stripe settings button that takes you to the rest.

Add Your API Keys

Copy keys from Stripe → Developers → API keys. The Stripe account section has:

  • Test mode, on by default. Only Stripe test cards work.
  • Test publishable key and Test secret key
  • Test webhook signing secret
  • Live publishable key, Live secret key and Live webhook signing secret

Secret keys can be standard (sk_) or restricted (rk_) keys. When you save, Stackless checks the keys with Stripe and shows the result. A wrong prefix, a missing half of a key pair or a key Stripe rejects shows an error. Live keys on an account that can’t take charges yet show a warning.

Stripe stays hidden at checkout until the selected mode has both keys.

Connect the Webhook

The webhook URL is https://yoursite.com/wp-json/stackless/v1/stripe/webhook, and the settings screen shows your exact URL. In Stripe → Developers → Webhooks, add an endpoint with this URL once for test mode and once for live mode. Subscribe to these events:

payment_intent.succeeded
payment_intent.payment_failed
payment_intent.processing
payment_intent.canceled
charge.refunded
charge.dispute.created
setup_intent.succeeded
setup_intent.setup_failed
payment_method.detached
payment_method.updated
payment_method.automatically_updated
checkout.session.completed
checkout.session.async_payment_succeeded
checkout.session.async_payment_failed
checkout.session.expired
invoice.paid
invoice.payment_failed
customer.subscription.updated
customer.subscription.deleted
customer.subscription.paused
customer.subscription.resumed

Paste each endpoint’s signing secret into the matching field. Without it, bank debits, refunds made in the Stripe Dashboard, disputes and removed cards won’t sync.

The checkout.session, invoice and customer.subscription events carry Stripe Managed Payments orders and renewals. When Stripe already has an endpoint for this URL, saving the Stripe settings adds any events it’s missing and tells you how many. If Stackless can’t update the endpoint, you’ll see a warning; add the missing events in Stripe yourself.

The Status panel below the settings shows whether the gateway is enabled, the verified test and live accounts, the webhook URL, the last signed webhook and the most recent events with their results.

Checkout Settings

  • Title: default “Card and more”.
  • Description: shown under the title.
  • Capture: Charge immediately, or Authorize only and capture when the order moves to Processing or Completed. Orders with subscriptions always charge immediately. Authorizations expire after 7 days, and cancelling the order releases them.
  • Saved payment methods: lets signed-in customers save and reuse methods. Subscription orders always save the method.
  • Statement descriptor suffix: up to 22 characters added after your account’s descriptor on card statements.
  • Payment form style: Match my theme, Stripe default, Flat or Night (dark).

Saved test cards and saved live cards are kept apart, so a test card never shows on a live checkout. When a customer deletes a saved method in My Account, it’s detached in Stripe too.

Express Checkout Buttons

The Express checkout section controls Apple Pay, Google Pay and Link buttons:

  • Show buttons on: Product pages, Cart and Checkout, all on by default.
  • Button label: Logo only, Buy with, Checkout with, Order with or Pay with.

Apple Pay also needs your domain added in Stripe → Settings → Payment method domains. On a product page, the wallet buys only that product: the shopper’s cart is set aside and restored afterward. Express buttons only show when the shopper can finish without filling a form. When checkout requires an account, guests see them only if WooCommerce can create the account on its own (account creation at checkout on, with automatic username and password).

Refunds and Disputes

Refund from the WooCommerce order screen as usual, in full or in part. An order that was only authorized can be released in full, but needs capturing before a partial refund. Refunds made in the Stripe Dashboard are recorded on the order through the webhook. A dispute adds a note with the reason, and puts a Processing or Completed order on hold.

Subscription Renewals

Stripe renews subscriptions automatically. It supports several subscriptions in one order, free-trial signups with nothing due today, payment method changes from My Account and next-payment date changes.

On the renewal date, the saved method is charged off-session:

  • If Stripe can’t be reached, the charge is retried up to 3 more times, 15, 30 and 45 minutes apart, with the same idempotency key so the customer is never charged twice.
  • If the bank asks for 3D Secure, the order gets a note with a link where the customer can confirm and pay. Automatic retries stop, because only the customer can confirm it: they have until the end of your retry period to pay from that link.
  • Bank debits that are still processing stay pending until Stripe confirms them.

When a renewal fails, Stackless records why, from Stripe’s decline code, and your retry schedule adapts to it:

What Stripe reportedRecorded asWhat happens next
Lost, stolen, closed, expired or invalid card, suspected fraud, no saved method, or a currency or amount Stripe can’t chargeHardWith Declined for good on (the default), no more automatic retries. The customer is asked to pay or change the payment method.
Insufficient funds or over a card limitFundsThe next retry waits at least 3 days.
The bank wants 3D SecureAuthenticationNo automatic retries. The customer pays from the link.
Stripe couldn’t be reachedNetworkRetried on your schedule.
Any other declineSoftRetried on your schedule.

Renewals, Failed Payments and Retries covers what happens after a failure.

Stripe Managed Payments

The Stripe module also adds a second gateway, Stripe Managed Payments (Stackless). With it, Stripe is the merchant of record for digital products: it handles sales tax, VAT and disputes, and bills subscriptions itself. It uses the same keys, webhook and test mode as this gateway. Setup and limits are in Sell Through Stripe Managed Payments.

Moving From the WooCommerce Stripe Plugin

When you move subscriptions from WooCommerce Subscriptions, the ones that renewed through the official WooCommerce Stripe plugin keep their saved payment method. Stackless reads each method from Stripe, checks that it’s attached to that Stripe customer, and saves it for this gateway with its real type, so a SEPA Direct Debit mandate stays a SEPA method and a card stays a card.

  • Use keys from the same Stripe account, for the mode the subscriptions were created in.
  • If Stripe can’t find a method, or it isn’t attached to that customer, the subscription switches to manual renewal and renewals are emailed as pay links.

Good to Know

  • Turn on Debug log under Advanced to write API calls and webhook results to WooCommerce → Status → Logs (stackless-stripe_gateway). Keys and card data are never logged.
  • The official Stripe plugin can run alongside this one. They use different gateway IDs, saved cards and webhooks.
  • Stripe hides itself for currencies it doesn’t support and for totals below Stripe’s minimum charge.
  • Billing Health lists Stripe problems: missing keys, keys from the wrong mode, a missing webhook signing secret, test mode on the live store, webhooks arriving in the other mode, and webhook events that failed or never finished in the last 7 days.
  • Post-purchase offers charge the saved card or payment method from the customer’s order in one click. If the bank asks for 3D Secure, the customer confirms on the order-pay page.
Share

Was this helpful?

Still stuck? Open a support ticket